Skip to main content

Troubleshooting

Common issues and their solutions.

Agent Issues​

Agent Not Sending Data​

Symptoms: No data appearing in dashboard after installation.

Solutions:

  1. Verify API Key

    {
      "skysignal": {
        "apiKey": "sk_live_xxx"
      }
    }

    The key must start with sk_live_ or sk_test_.

  2. Check Agent Startup

    # Look for SkySignal logs on startup
    meteor run --settings settings.json
    # Should see: "SkySignal: Connected to dash.skysignal.app"

  3. Verify Network Connectivity

    # Test from your server
    curl -I https://dash.skysignal.app/health
    # Should return 200 OK

  4. Check Firewall Rules

    • Allow outbound HTTPS to dash.skysignal.app
    • Allow outbound on port 443

High Memory Usage from Agent​

Symptoms: Memory increases after installing agent.

Solutions:

  1. Reduce Sample Rate

    {
      "skysignal": {
        "apiKey": "sk_live_xxx",
        "sampleRate": 0.5
      }
    }

  2. Disable Unused Collectors

    {
      "skysignal": {
        "apiKey": "sk_live_xxx",
        "enableRUM": false,
        "enableHTTP": false
      }
    }

  3. Increase Flush Interval

    {
      "skysignal": {
        "apiKey": "sk_live_xxx",
        "flushInterval": 30000
      }
    }

Method Names Showing as "unknown"​

Symptoms: Method traces appear but names are "unknown".

Solutions:

  1. Ensure Methods are Defined Before Agent Loads

    // ✅ Correct order
    import './methods';  // Define methods first
    import '@skysignal/agent';  // Then import agent

  2. Check for Dynamic Method Registration

    // If using ValidatedMethod, ensure proper naming
    export const myMethod = new ValidatedMethod({
      name: 'myModule.myMethod',  // Explicit name required
      // ...
    });

Dashboard Issues​

No Data Showing​

Symptoms: Dashboard loads but shows "No data available".

Solutions:

  1. Check Time Range

    • Default is last 24 hours
    • Adjust to "Last 7 days" if just installed

  2. Verify Site Selection

    • Ensure correct site is selected
    • Check you have access to the site

  3. Wait for Data Processing

    • Data may take 1-2 minutes to appear
    • Check "Last seen" timestamp in site settings

Charts Not Loading​

Symptoms: Blank charts or loading spinners.

Solutions:

  1. Clear Browser Cache

    Chrome: Ctrl+Shift+Delete → Cached images and files

  2. Check Console for Errors

    F12 → Console tab → Look for red errors

  3. Try Different Browser

    • Supported: Chrome, Firefox, Safari, Edge (latest)

Slow Dashboard Performance​

Symptoms: Dashboard takes long to load.

Solutions:

  1. Reduce Time Range

    • Use shorter time ranges (1h, 6h) for faster queries

  2. Use Filters

    • Filter by specific method or host
    • Reduces data volume

  3. Check Network

    • Slow connection affects dashboard
    • Try from different network

Data Issues​

Missing Traces​

Symptoms: Some method calls not appearing.

Solutions:

  1. Check Sample Rate If sample rate is below 1, some traces won't be captured. Set it to 1.0 in your settings.json to capture everything:

    {
      "skysignal": {
        "sampleRate": 1.0
      }
    }

  2. Verify Method Tracking Some methods may be filtered. Check your settings.json for exclusions:

    {
      "skysignal": {
        "excludeMethods": ["debug.*"]
      }
    }

  3. Check for Errors

    • Failed method calls may still be captured
    • Look in Errors tab

Incorrect Response Times​

Symptoms: Response times seem wrong.

Solutions:

  1. Understand Measurement Point

    • Server-side time only (not network)
    • Includes async operations within method

  2. Check for Long-Running Operations

    Meteor.methods({
      'myMethod'() {
        this.unblock();  // Without this, includes wait time
        // ...
      }
    });

Duplicate Errors​

Symptoms: Same error appears multiple times.

Solutions:

  1. Errors are Grouped by Default

    • Same error message = same group
    • Check occurrence count

  2. Enable Error Fingerprinting

    {
      "skysignal": {
        "errorTracking": {
          "fingerprint": ["message", "type", "method"]
        }
      }
    }

Authentication Issues​

"Invalid API Key" Error​

Solutions:

  1. Verify Key Format

    Production: sk_live_xxxxx (28+ characters)
    Test: sk_test_xxxxx

  2. Check for Whitespace

    // ❌ Wrong
    apiKey: ' sk_live_xxx '  // Has spaces

    // ✅ Correct
    apiKey: 'sk_live_xxx'

  3. Regenerate Key

    • Site Settings → API → Rotate Key

"Unauthorized" in Dashboard​

Solutions:

  1. Log Out and Back In

    • Session may have expired

  2. Check Email Verification

    • Must verify email to access dashboard

  3. Check Team Membership

    • Ensure you're added to the customer account

Performance Issues​

High CPU on Server​

Symptoms: CPU spikes after installing agent.

Solutions:

  1. Enable Sampling

    {
      "skysignal": {
        "sampleRate": 0.1
      }
    }

  2. Disable Detailed Tracing

    {
      "skysignal": {
        "traceDetails": false
      }
    }

Increased Latency​

Symptoms: Methods slower after agent installation.

Solutions:

  1. Agent adds ~1-2ms overhead max

    • If seeing more, check other factors

  2. Use Async Reporting The default is async. Verify this hasn't been changed in your settings.json:

    {
      "skysignal": {
        "sync": false
      }
    }

Getting Help​

Collect Debug Information​

Before contacting support, enable debug logging in your settings.json:

{
  "skysignal": {
    "apiKey": "sk_live_xxx",
    "debug": true
  }
}

Then collect:

  • Agent version (npm list @skysignal/agent)
  • Meteor version (meteor --version)
  • Node version (node --version)
  • Browser console logs
  • Server logs with SkySignal output

Contact Support​

Include:

  • Description of the issue
  • Steps to reproduce
  • Debug information collected above
  • Screenshots if applicable