Tyk "Couldn't load API definition" (JSON) in CI

By Daniel Zoghalchali·Latchkey

The Tyk gateway tried to load an API definition from a JSON file and failed: the JSON is invalid, or a required field like api_id or the listen path is missing. The gateway logs the error and does not serve that API.

What this error means

Tyk logs "Couldn't load API" or "Error: invalid character ... in JSON" at startup, and the affected API returns 404 because it never registered.

level=error msg="Couldn't load app config file" error="invalid character '}' looking for beginning of object key string"

Common causes

Invalid JSON in the API definition

A trailing comma or stray brace makes the file unparseable, so the gateway cannot register the API.

A missing required field

The definition lacks api_id, name, or a listen_path, so Tyk rejects it as incomplete.

How to fix it

Validate the API definition JSON

1. Run the file through a JSON validator to find the syntax error.
2. Confirm required fields (api_id, name, proxy.listen_path, proxy.target_url) are present.
3. Reload the gateway and confirm the API registers.

jq empty apps/my-api.json && echo "valid JSON"

Keep required fields in the definition

A minimal Tyk API definition needs an id, a listen path, and a target URL.

{
  "api_id": "my-api",
  "name": "My API",
  "proxy": {
    "listen_path": "/my-api/",
    "target_url": "http://backend:8080"
  }
}

How to prevent it

• Validate API definition JSON in CI before deploying.
• Keep a schema check for required fields like listen_path and target_url.
• Avoid hand-editing JSON without a linter.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation