Connection Issues

This guide covers authentication and network connectivity problems with Spekra.

"Invalid API Key" Error

Symptoms

• Error message: "Invalid API key" or "Unauthorized"
• HTTP status 401 in debug output

Solutions

1. Verify the Key Exists

Check that the environment variable is set:

echo $SPEKRA_API_KEY

If empty, set it:

export SPEKRA_API_KEY=sk_your_api_key_here

2. Check for Extra Characters

API keys should:

• Start with sk_
• Contain only alphanumeric characters
• Have no leading/trailing spaces
• Have no quotes around them in env vars

# Wrong
export SPEKRA_API_KEY="sk_abc123"  # Quotes may cause issues

# Right
export SPEKRA_API_KEY=sk_abc123

3. Verify the Key is Valid

1. Go to Settings → API Keys
2. Check if your key is listed
3. If not, create a new one

4. Check Key in CI Secrets

For CI environments:

• Verify the secret name matches exactly
• Check the secret isn't empty
• Ensure the secret is available to the job

GitHub Actions

# Check that secret is available
- name: Debug API key
  run: |
    if [ -z "$SPEKRA_API_KEY" ]; then
      echo "API key not set!"
      exit 1
    else
      echo "API key is set (length: ${#SPEKRA_API_KEY})"
    fi
  env:
    SPEKRA_API_KEY: ${{ secrets.SPEKRA_API_KEY }}

Network Connection Failures

Symptoms

• Timeout errors
• "Network error" or "ECONNREFUSED"
• Tests complete but no data in Spekra

Solutions

1. Check Network Access

Verify you can reach Spekra:

curl -v https://spekra.dev/api/health

Expected response:

{"status": "ok"}

2. Check Firewall/Proxy

If behind a corporate firewall:

• Add spekra.dev to allowlist
• Configure proxy settings if needed

For proxy configuration:

export HTTPS_PROXY=http://proxy.company.com:8080
npx playwright test

3. Increase Timeout

If on a slow network, increase the timeout:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  timeout: 60000, // 60 seconds
}]

4. Check DNS Resolution

Verify DNS is working:

nslookup spekra.dev

SSL/TLS Errors

Symptoms

• "Unable to verify certificate"
• "SSL_ERROR_SYSCALL"
• Certificate errors

Solutions

1. Update CA Certificates

On Linux:

sudo apt-get update && sudo apt-get install ca-certificates

2. Check System Time

SSL errors can occur if your system clock is wrong:

date

Sync if needed:

sudo ntpdate pool.ntp.org

3. Corporate Proxy Certificate

If your company uses SSL inspection, you may need to add their CA certificate:

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.crt
npx playwright test

"Request Timeout" Error

Symptoms

• Reporter says "request timed out"
• Tests complete very slowly

Solutions

1. Check Network Latency

ping spekra.dev

High latency (>500ms) may cause issues.

2. Reduce Batch Size

If you have many tests, reduce batch size:

['@spekra/playwright', {
  apiKey: process.env.SPEKRA_API_KEY,
  batchSize: 50, // Smaller batches
}]

3. Check CI Resources

In CI, resource constraints can cause slowness:

• Increase runner size
• Reduce parallelism
• Check for resource contention

Still Having Issues?

SPEKRA_DEBUG=true npx playwright test 2>&1 | tee spekra-debug.log

Include this log when opening a support issue.