Error Codes

Reference for all error codes returned by the Invarium MCP server.

When an MCP tool call fails, use this reference to understand what went wrong and how to fix it.

Error response format

When an MCP tool call encounters an error, it returns a plain text error message describing the issue. For example:

Error: Agent not found: customer-support-agent. Upload a blueprint first.

Error: Blueprint validation failed. Required field 'tools' is missing.

The error message includes the cause and typically suggests a fix.

Error codes

AUTH_FAILED

The API key is invalid, expired, or missing.

Common causes:

• The INVARIUM_API_KEY environment variable is not set
• The API key has been revoked in the dashboard
• The API key has a typo or is incomplete
• The API key belongs to a different workspace than expected

How to fix:

1. Go to the dashboard and navigate to API Keys
2. Check if your key is listed and active
3. If not, create a new key
4. Update your MCP server configuration with the new key:

{
  "env": {
    "INVARIUM_API_KEY": "inv_your_new_key_here"
  }
}

5. Restart your MCP client to pick up the new configuration

Example error:

Error: Authentication failed. Check your INVARIUM_API_KEY.

INVALID_BLUEPRINT

The blueprint YAML is malformed or does not match the required schema.

Common causes:

• Invalid YAML syntax (bad indentation, missing quotes around special characters)
• Missing required fields (agent_name, tools)
• Tool definition missing required fields (name, description, parameters)
• agent_name contains invalid characters (only lowercase, numbers, hyphens)
• Blueprint size exceeds the 500 KB limit

How to fix:

1. Validate your YAML syntax with a linter
2. Compare your blueprint against the Blueprint Schema
3. See Blueprint Examples for known-good examples

Example error:

Error: Blueprint validation failed. Required field 'tools' is missing.

GENERATION_IN_PROGRESS

A test generation is already running for this agent.

Common causes:

• You called invarium_generate_tests while a previous generation for the same agent is still running
• A generation was started but the client disconnected before receiving the generation ID

How to fix:

1. Wait for the current generation to complete (typically 10-30 seconds)
2. Use invarium_get_tests with the agent name to check if results are available
3. If the previous generation seems stuck (over 2 minutes), wait for the timeout (120 seconds) and try again

AGENT_NOT_FOUND

No agent with the specified name exists in your workspace.

Common causes:

• Typo in the agent name
• The blueprint has not been uploaded yet
• The agent was deleted from the dashboard
• The agent belongs to a different workspace than the API key

How to fix:

1. Check the exact agent name — it is case-sensitive and uses kebab-case
2. Upload a blueprint first with invarium_upload_blueprint if the agent does not exist yet
3. Verify you are using an API key from the correct workspace

Example error:

Error: Agent not found: customer-support-agent. Upload a blueprint first.

INVALID_RESULTS

The results payload is malformed or missing required fields.

Common causes:

• The results parameter is not a valid JSON array
• Individual result objects are missing required fields (scenario_id, user_message, agent_response)
• The scenario_id does not match any generated test case

How to fix:

1. Ensure each result has at minimum: scenario_id, user_message, and agent_response
2. Validate that scenario_id values match the IDs from invarium_get_tests
3. Validate the JSON in your editor or with a linter before syncing

Example error:

Error: Result validation failed. Required field 'agent_response' is missing at index 3.

SERVER_ERROR

An unexpected error occurred on the Invarium server.

Common causes:

• Temporary server issue
• An edge case in the Scenario Generator
• Database connectivity issue

How to fix:

1. Wait 30 seconds and retry the request
2. If the error persists, check Invarium’s status page for outages
3. If the issue continues, report it to support@invarium.dev with:
   • The full error message
   • The tool you were calling
   • The parameters you passed (redact any sensitive data)

QUOTA_EXCEEDED

You have reached your plan’s monthly limit for the requested operation.

Common causes:

• The monthly test generation quota for your plan has been exhausted
• Multiple team members sharing the same workspace consumed the quota

How to fix:

1. Run invarium_usage to see your current quota and remaining allowance
2. Wait for the quota to reset at the start of the next billing cycle
3. Upgrade your plan at app.invarium.dev/settings/billing for a higher quota

Example error:

Error: Monthly generation quota exceeded. 50/50 generations used. Resets on 2025-08-01.

RATE_LIMITED

Too many requests in a short time period.

Common causes:

• Calling the same tool in rapid succession (e.g., polling invarium_get_tests in a tight loop)
• Multiple MCP clients connected to the same workspace making concurrent requests

How to fix:

1. Wait a few seconds and retry the request
2. When polling for test generation results, wait at least 5-10 seconds between checks
3. Avoid making concurrent calls to the same tool from multiple clients

Example error:

Error: Rate limited. Please wait before retrying.

VALIDATION_ERROR

A request parameter failed validation.

Common causes:

• A required parameter is missing or empty
• A parameter value is outside the allowed range (e.g., page=0, limit=-1)
• A string parameter does not match the expected format (e.g., invalid JSON for expected_tools or tags)
• An enum parameter has an unrecognized value (e.g., status='unknown', action='reset')

How to fix:

1. Check the tool’s parameter documentation for allowed values and formats
2. Ensure JSON string parameters (expected_tools, tags, results) contain valid JSON arrays
3. Verify enum parameters match one of the documented values exactly

Example errors:

Error: Invalid status 'unknown'. Choose from: failed, flaky, not_run, passed.

Error: Invalid JSON for expected_tools: Expecting value. Provide a JSON array, e.g. ["search", "fetch"].

Debugging tips

1. Read the error message carefully. It contains specific information about what went wrong and typically suggests a fix.
2. Use invarium_connect first. If you are getting AUTH_FAILED errors, test the connection before trying other tools.
3. Validate locally. Before uploading blueprints, validate the YAML in your editor or with a linter. Before syncing results, validate the JSON results payload.