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 JSON is malformed or does not match the required schema.

Common causes:

• Invalid JSON syntax (missing commas, unclosed brackets)
• 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 JSON 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.ai with:
   • The full error message
   • The tool you were calling
   • The parameters you passed (redact any sensitive data)

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 JSON locally. Before uploading blueprints or syncing results, validate the JSON in your editor or with a linter.