Troubleshooting Guide

Common issues, solutions, and debugging techniques for FinFocus Core.

Table of Contents

• Installation Issues
• Pulumi Integration
• Plugin Problems
• Cost Calculation Issues
• Performance Problems
• Configuration Issues
• Network and Authentication
• Debug Mode
• Getting Help

Installation Issues

Binary Not Found

Problem: Command finfocus not found after installation.

$ finfocus --help
bash: finfocus: command not found

Solutions:

1. Check if binary is in PATH:

   which finfocus
   echo $PATH

2. Add to PATH temporarily:

   export PATH=$PATH:/usr/local/bin

3. Add to PATH permanently:

   # For bash
   echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
   source ~/.bashrc
   
   # For zsh
   echo 'export PATH=$PATH:/usr/local/bin' >> ~/.zshrc
   source ~/.zshrc

4. Use full path:

   /usr/local/bin/finfocus --help

Permission Denied

Problem: Permission denied when running binary.

$ finfocus --help
bash: ./finfocus: Permission denied

Solutions:

1. Make binary executable:

   chmod +x /usr/local/bin/finfocus

2. Check file permissions:

   ls -la /usr/local/bin/finfocus
   # Should show: -rwxr-xr-x (executable permissions)

3. For downloaded files:

   chmod +x ./finfocus
   sudo mv ./finfocus /usr/local/bin/

macOS Security Warning

Problem: macOS blocks unsigned binary.

"finfocus" cannot be opened because the developer cannot be verified.

Solutions:

1. Allow via System Preferences:

   • Go to System Preferences > Security & Privacy
   • Click “Allow Anyway” for finfocus

2. Command line bypass:

   sudo spctl --add /usr/local/bin/finfocus
   sudo xattr -dr com.apple.quarantine /usr/local/bin/finfocus

3. Temporary bypass:

   xattr -dr com.apple.quarantine ./finfocus
   ./finfocus --help

Version Compatibility

Problem: Binary doesn’t work on your system architecture.

Solutions:

1. Check system architecture:

   uname -m
   # x86_64 = amd64, aarch64 = arm64

2. Download correct binary:

   # For Intel Macs
   curl -L https://github.com/rshade/finfocus/releases/latest/download/finfocus-darwin-amd64 -o finfocus
   
   # For Apple Silicon Macs
   curl -L https://github.com/rshade/finfocus/releases/latest/download/finfocus-darwin-arm64 -o finfocus

Pulumi Integration

Pulumi Plan JSON Issues

Problem: pulumi preview --json fails or produces invalid JSON.

Diagnosis:

# Test Pulumi JSON output
pulumi preview --json > plan.json
cat plan.json | jq '.' # Should parse without errors

Solutions:

1. Fix malformed JSON:

   # Check JSON validity
   python -m json.tool plan.json
   # or
   jq '.' plan.json

2. Pulumi authentication issues:

   pulumi login
   pulumi stack select your-stack-name

3. Resource provider issues:

   # Update providers
   pulumi plugin install
   
   # List available providers
   pulumi plugin ls

4. Use stack export as alternative:

   # If preview fails, try current state
   pulumi stack export > current-state.json
   finfocus cost projected --pulumi-json current-state.json

Empty Pulumi Plan

Problem: Pulumi plan contains no resources.

$ finfocus cost projected --pulumi-json plan.json
No resources found in Pulumi plan

Solutions:

1. Check plan contents:

   jq '.steps | length' plan.json
   jq '.steps[0]' plan.json

2. Verify Pulumi stack:

   pulumi stack ls
   pulumi stack select correct-stack
   pulumi preview

3. Check for pending changes:

   pulumi up --diff

Resource Type Recognition

Problem: Resources not recognized by FinFocus.

Resource type 'custom:provider/resource:Type' not supported

Solutions:

1. Check supported resource types:

   # Common supported patterns:
   # aws:ec2/instance:Instance
   # aws:s3/bucket:Bucket
   # aws:rds/instance:Instance

2. Plugin Compatibility: Some plugins may require specific resource type formats (e.g., aws:ec2:Instance vs aws:ec2/instance:Instance).

   • Check plugin documentation for supported types.
   • Ensure your Pulumi provider versions are compatible with the plugin.

3. Use resource filtering:

   # Filter to supported resources only
   finfocus cost projected --pulumi-json plan.json --filter "type=aws:ec2"

4. Create custom pricing spec:

   mkdir -p ~/.finfocus/specs
   # Create YAML spec for custom resource type

Plugin Problems

Plugin Not Found

Problem: Plugins not discovered or loaded.

$ finfocus plugin list
No plugins found

Solutions:

1. Check plugin directory structure:

   ls -la ~/.finfocus/plugins/
   ls -la ~/.finfocus/plugins/*/*/

2. Verify directory structure:

   ~/.finfocus/plugins/
   └── kubecost/
       └── 1.0.0/
           └── finfocus-kubecost

3. Make plugin executable:

   chmod +x ~/.finfocus/plugins/*/*/finfocus-*

4. Check plugin names:

   # Plugin binary must start with 'finfocus-'
   ls ~/.finfocus/plugins/*/*/finfocus-*

Plugin Validation Failures

Problem: Plugin validation fails.

$ finfocus plugin validate
kubecost: FAILED - connection timeout

Solutions:

1. Test plugin directly:

   ~/.finfocus/plugins/kubecost/1.0.0/finfocus-kubecost
   # Should start and show port information

2. Check plugin logs:

   PLUGIN_DEBUG=1 finfocus plugin validate --adapter kubecost

3. Network connectivity:

   # Test external API connectivity
   curl -v http://kubecost.example.com:9090/api/v1/costDataModel

4. Authentication setup:

   # Verify required environment variables
   env | grep -E "(KUBECOST|AWS|AZURE|GCP)"

Plugin Communication Errors

Problem: gRPC communication failures between core and plugins.

Error: failed to connect to plugin: context deadline exceeded

Solutions:

1. Increase timeout:

   export PLUGIN_TIMEOUT=60s
   finfocus cost actual --adapter kubecost --from 2025-01-01

2. Check port conflicts:

   # List processes using common gRPC ports
   lsof -i :50051
   netstat -tulpn | grep :50051

3. Firewall issues:

   # Temporarily disable firewall for testing
   sudo ufw disable  # Ubuntu
   sudo systemctl stop firewalld  # CentOS/RHEL

4. Plugin process issues:

   # Kill any stuck plugin processes
   pkill finfocus-kubecost
   ps aux | grep finfocus

Plugin Exits at Startup

Problem: A plugin stops before it starts serving, usually because its configuration is missing or invalid. FinFocus reports the exit status and the last lines the plugin wrote to stderr, for example in the Notes column of finfocus plugin list:

Failed: plugin exited before binding to port (exit status 1): config: config: baseUrl must be an http(s) URL with a host

Solutions:

1. Fix the setting the message names, then run finfocus plugin list again.
2. The excerpt is short and comes only from the plugin’s structured (JSON) log lines. A plugin that writes plain text instead gets its stderr is not a structured log, see the FinFocus log file. For the full plugin output, read the FinFocus log file or run the command with --debug.

FinFocus does not retry a plugin that exits on its own, unless the plugin reports that its port was already in use. The --port and pluginsdk upgrade hint in the log applies only to a plugin that keeps running without binding its port.

Plugin Is Slow to Start

Problem: A large plugin, such as aws-public with its embedded pricing data, can take several seconds to load the first time it runs after install or reboot. When it does not open its port in time, FinFocus reports how long it waited:

Failed: plugin failed to bind to port within 20s: timeout waiting for plugin to bind: context deadline exceeded

Solutions:

1. Run the command again. Later starts read the binary from the disk cache and are much faster.
2. finfocus plugin list and the dashboard’s plugin checks wait 20 seconds for a plugin to start and answer. Cost commands wait up to 65 seconds for the plugin to open its port (125 seconds when CI=true). These limits are fixed.
3. A plugin that never opens its port within those limits is stuck, not slow. Run the command with --debug and read the FinFocus log file.

Cost Calculation Issues

No Cost Data Available

Problem: All resources show “$0.00” or “No pricing information available”.

aws:ec2/instance:Instance    none    $0.00    USD    No pricing information available

Solutions:

1. Install pricing plugins:

   # Install appropriate cost plugins
   # See Plugin System documentation

2. Create local pricing specs:

   mkdir -p ~/.finfocus/specs
   cat > ~/.finfocus/specs/aws-ec2-t3-micro.yaml << 'EOF'
   provider: aws
   service: ec2
   sku: t3.micro
   currency: USD
   pricing:
     onDemandHourly: 0.0104
     monthlyEstimate: 7.59
   EOF

3. Use specific adapter:

   finfocus cost projected --pulumi-json plan.json --adapter aws-plugin

4. Check resource properties:

   # Verify resource has necessary properties
   jq '.steps[0].inputs' plan.json

Missing Cost Data (Empty Inputs)

Problem: Logs show “resource descriptor missing required fields (sku, region)” or plugins return “not supported” because properties are missing.

Diagnosis: This often happens when pulumi preview --json structure changes (e.g., nesting inputs under newState).

Solution: Ensure you are using a compatible version of finfocus that handles the JSON structure of your Pulumi CLI version.

• Update finfocus to the latest version.
• Check pulumi version and ensure compatibility.

Region Not Resolved

Problem: A resource shows $0.00 with a note or .finfocus.errors entry such as plugin call failed: InvalidArgument: region is required for GetProjectedCost. This means no region could be resolved for the resource, so the pricing plugin rejected the request.

Solution: Provide a region through one of the supported sources, in the order core checks them:

1. A region input on the resource.

2. An availabilityZone input on the resource (e.g. us-west-2a).

3. An ARN property on the resource (the region segment is parsed from it).

4. The region of the resource’s AWS provider: the region input of its pulumi:providers:aws resource, or that resource’s region output when it has no region input. A secret or unknown region input gives no provider region. Core finds the provider through the resource’s provider reference in the stack state or the preview. The price after a change uses the provider the preview assigns; the price before it, actual costs, and a delete use the deployed provider. A --pulumi-json run inside a Pulumi project also reads the stack state. Without state, the provider is seen only when the preview creates or updates it.

5. The AWS_REGION or AWS_DEFAULT_REGION environment variable:

   AWS_REGION=us-west-2 finfocus cost projected --pulumi-json plan.json

Core reads a region from the provider resource, not from stack configuration (aws:region) directly. Stack configuration reaches the provider resource’s region input, so a stack with a region configured resolves through step 4 once its state or preview includes the provider.

A regionless S3 bucket is expected to price at $0.00 without an error: the plugin accepts it, and bucket contents cannot be measured from a plan.

Inaccurate Cost Estimates

Problem: Cost estimates seem too high or too low.

Diagnosis:

1. Compare with manual calculations:

   # For t3.micro: $0.0104/hour × 730 hours = $7.59/month

2. Check pricing spec accuracy:

   cat ~/.finfocus/specs/aws-ec2-t3-micro.yaml

3. Verify resource configuration:

   jq '.steps[] | select(.type == "aws:ec2/instance:Instance") | .inputs' plan.json

Solutions:

1. Update pricing specifications:

   # Get latest AWS pricing
   # Update local specs accordingly

2. Use region-specific pricing:

   # Different regions have different costs
   # Ensure specs match your deployment region

3. Account for reserved instances:

   # Pricing specs should reflect your actual pricing model
   # (on-demand vs reserved vs spot)

Historical Cost Data Issues

Problem: Actual cost queries return no data or errors.

$ finfocus cost actual --pulumi-json plan.json --from 2025-01-01
Error: no cost data available for time range

Solutions:

1. Check date range:

   # Ensure date range is valid and not too recent
   finfocus cost actual --pulumi-json plan.json --from 2025-01-07 --to 2025-01-14

2. Billing data lag:

   # Most billing APIs have 24-48 hour delays
   # Try querying older date ranges
   finfocus cost actual --pulumi-json plan.json --from 2025-01-01 --to 2025-01-02

3. Resource matching:

   # Resources might not exist in the historical time range
   # Check when resources were actually deployed

4. Plugin configuration:

   # Verify plugin can access billing APIs
   export KUBECOST_API_URL="http://kubecost.example.com:9090"
   finfocus plugin validate --adapter kubecost

Performance Problems

Slow Cost Calculations

Problem: Cost calculations take too long to complete.

Solutions:

1. Use specific adapter:

   # Avoid querying all plugins
   finfocus cost projected --pulumi-json plan.json --adapter kubecost

2. Filter resources:

   # Process fewer resources
   finfocus cost projected --pulumi-json plan.json --filter "type=aws:ec2"

3. Increase timeout:

   export PLUGIN_TIMEOUT=300s
   finfocus cost actual --pulumi-json plan.json --from 2025-01-01

4. Parallel processing:

   # Split large plans into smaller chunks
   jq '.steps[:10]' plan.json > plan-chunk1.json
   jq '.steps[10:20]' plan.json > plan-chunk2.json

Memory Usage

Problem: High memory usage with large Pulumi plans.

Solutions:

1. Process in batches:

   # Split large plans
   jq '.steps | .[0:100]' large-plan.json > batch1.json
   jq '.steps | .[100:200]' large-plan.json > batch2.json

2. Use NDJSON output:

   # More memory-efficient for large datasets
   finfocus cost projected --pulumi-json plan.json --output ndjson

3. Filter early:

   # Reduce processing load
   finfocus cost projected --pulumi-json plan.json --filter "provider=aws"

Network Timeouts

Problem: Requests to external APIs timeout.

Solutions:

1. Check network connectivity:

   curl -v https://api.aws.com/
   ping kubecost.example.com

2. Increase timeouts:

   export HTTP_TIMEOUT=60s
   export PLUGIN_TIMEOUT=300s

3. Configure proxy:

   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080

4. Retry configuration:

   export MAX_RETRIES=5
   export RETRY_DELAY=5s

Configuration Issues

Directory Permissions

Problem: Cannot create or access configuration directories.

Solutions:

1. Create directories manually:

   mkdir -p ~/.finfocus/plugins
   mkdir -p ~/.finfocus/specs
   chmod 755 ~/.finfocus/

2. Fix ownership:

   chown -R $USER:$USER ~/.finfocus/

3. Check disk space:

   df -h ~

Environment Variables

Problem: Environment variables not being recognized.

Solutions:

1. Check variable names:

   env | grep FINFOCUS
   env | grep -E "(AWS|KUBECOST|AZURE)"

2. Export variables properly:

   export KUBECOST_API_URL="http://kubecost.example.com:9090"
   export AWS_REGION="us-west-2"

3. Persistent environment setup:

   # Add to shell profile
   echo 'export KUBECOST_API_URL="http://kubecost.example.com:9090"' >> ~/.bashrc
   source ~/.bashrc

Configuration Files

Problem: Configuration files not being loaded.

Solutions:

1. Check file locations:

   ls -la ~/.finfocus/
   ls -la ~/.finfocus/plugins/*/*/config.*

2. Validate YAML syntax:

   python -c "import yaml; yaml.safe_load(open('config.yaml'))"
   # or
   yq eval '.' config.yaml

3. Check file permissions:

   ls -la ~/.finfocus/specs/*.yaml
   chmod 644 ~/.finfocus/specs/*.yaml

Network and Authentication

API Authentication Failures

Problem: Plugin cannot authenticate with external APIs.

Error: authentication failed: invalid API key

Solutions:

1. Verify credentials:

   # Test API credentials manually
   curl -H "Authorization: Bearer $API_TOKEN" https://api.provider.com/test

2. Check credential format:

   # Ensure no extra whitespace or newlines
   echo -n "$API_KEY" | hexdump -C

3. Rotate credentials: Generate new API keys if current ones are invalid.

4. Check credential permissions: Ensure API key has required permissions for cost data access.

SSL Certificate Issues

Problem: SSL certificate verification failures.

Error: x509: certificate signed by unknown authority

Solutions:

1. Update CA certificates:

   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get install ca-certificates
   
   # CentOS/RHEL
   sudo yum update ca-certificates

2. Disable SSL verification (temporary):

   export INSECURE_SKIP_VERIFY=true

3. Add custom CA certificate:

   # Add your organization's CA certificate
   sudo cp custom-ca.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates

Proxy Configuration

Problem: Network requests fail behind corporate proxy.

Solutions:

1. Configure HTTP proxy:

   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   export NO_PROXY=localhost,127.0.0.1,.internal.domain

2. Authenticated proxy:

   export HTTP_PROXY=http://username:password@proxy.company.com:8080

3. Plugin-specific proxy:

   # Some plugins might need specific proxy configuration
   export KUBECOST_PROXY_URL=http://proxy.company.com:8080

Debug Mode

Enable Debug Logging

# Global debug mode
finfocus --debug cost projected --pulumi-json plan.json

# Plugin-specific debugging
export PLUGIN_DEBUG=1
export PLUGIN_LOG_LEVEL=debug
finfocus cost actual --adapter kubecost --from 2025-01-01

Verbose Output

# Increase verbosity
finfocus -v cost projected --pulumi-json plan.json

# Maximum verbosity
finfocus -vv cost actual --adapter kubecost --from 2025-01-01

Log Analysis

# Save logs to file
finfocus --debug cost projected --pulumi-json plan.json > debug.log 2>&1

# Search for specific errors
grep -i "error\|failed\|timeout" debug.log

# Check plugin communication
grep -i "grpc\|plugin\|connect" debug.log

Plugin Debugging

# Test plugin directly
~/.finfocus/plugins/kubecost/1.0.0/finfocus-kubecost &
PLUGIN_PID=$!

# Test gRPC connection
grpcurl -plaintext localhost:50051 finfocus.v1.CostSourceService/Name

# Clean up
kill $PLUGIN_PID

Common Error Messages

“No such file or directory”

Error: exec: "finfocus-kubecost": executable file not found in $PATH

Solution: Plugin binary missing or not executable.

ls -la ~/.finfocus/plugins/kubecost/1.0.0/
chmod +x ~/.finfocus/plugins/kubecost/1.0.0/finfocus-kubecost

“Connection refused”

Error: connection refused: dial tcp 127.0.0.1:50051: connect: connection refused

Solution: Plugin process not running or wrong port.

# Restart plugin validation
finfocus plugin validate
# Check for port conflicts
lsof -i :50051

“Context deadline exceeded”

Error: context deadline exceeded

Solution: Increase timeout or check network connectivity.

export PLUGIN_TIMEOUT=60s
# Check network connectivity to external APIs

“Invalid JSON”

Error: invalid character 'N' looking for beginning of value

Solution: Pulumi plan JSON is malformed.

# Re-generate plan
pulumi preview --json > plan.json
# Validate JSON
jq '.' plan.json

Getting Help

Community Support

1. GitHub Issues: https://github.com/rshade/finfocus/issues
2. Discussions: https://github.com/rshade/finfocus/discussions
3. Documentation: Check all docs in this repository

Bug Reports

When reporting bugs, include:

1. Version information:

   finfocus --version

2. System information:

   uname -a
   go version  # if building from source

3. Debug logs:

   finfocus --debug [command] > debug.log 2>&1

4. Configuration details:

   ls -la ~/.finfocus/
   env | grep -E "(PULUMI|AWS|KUBECOST)"

5. Minimal reproduction:

   • Steps to reproduce the issue
   • Expected vs actual behavior
   • Sample Pulumi plan (sanitized)

Feature Requests

1. Check existing issues/discussions first
2. Describe the use case clearly
3. Provide examples of desired behavior
4. Consider contributing implementation

Self-Help Checklist

Before seeking help:

• Check this troubleshooting guide
• Try with --debug flag
• Verify installation with finfocus --version
• Test with provided examples
• Check plugin status with finfocus plugin validate
• Review environment variables and configuration
• Test network connectivity to external APIs
• Search existing GitHub issues

Professional Support

For enterprise support or custom plugin development:

• Contact the maintainers through GitHub
• Consider sponsoring the project
• Explore commercial support options

Related Documentation

• Installation Guide - Setup and installation help
• User Guide - Usage instructions and examples
• Plugin System - Plugin development and management
• Cost Calculations - Understanding cost methodologies