Troubleshooting & Diagnostics

If your app logs ACFG_TIMEOUT or the sync progress stalls past 80%, this is usually a network or proxy restriction.

• Verify outbound HTTPS connectivity to *.appconfig.json
• Check if your corporate firewall is blocking WebSocket upgrades
• Increase timeout_ms in your SDK initialization (default: 5000)
• Force manual sync: acfg sync --force

Still stuck? Run acfg diagnose --network and share the output.

This error indicates mismatched or expired credentials.

• Ensure you're using the correct key for your environment (dev, staging, or prod)
• Keys starting with acfg_live_ are production-only
• Rotate expired keys in Dashboard → Settings → API Access
• Check for trailing spaces in environment variables

Never hardcode keys. Use ACFG_API_KEY env var.

Common when there's a version mismatch between the SDK and the config schema.

• Update SDK: npm update @appconfig/sdk or equivalent
• Verify schema_version in your root config matches the SDK requirement
• Check for TypeScript/Node version incompatibilities
• Enable verbose logging: ACFG_DEBUG=true node app.js

The platform rejects configs that don't conform to the defined schema.

• Run local validation: acfg validate ./config.json
• Check for trailing commas, missing quotes, or undefined types
• Ensure all required fields from your schema are present
• Use the online JSON formatter in the dashboard editor