Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt

Use this file to discover all available pages before exploring further.

Common errors you may encounter when using AgentMark and how to resolve them. Every error string below is a literal match from the source — search your logs for the exact text.

​
Connection and authentication

​
Cannot connect to local dev server

Error (from Node fetch): fetch failed — cause: { code: 'ECONNREFUSED', address: '127.0.0.1', port: 9418, ... } Cause: The local dev server isn’t running on the port your ApiLoader.local() is pointing at. Solution:
  1. Start the dev server in a separate terminal: 
    npx agentmark dev
  2. Verify it’s reachable at http://localhost:9418.
  3. If using a custom port: 
    npx agentmark dev --api-port 9500

    ApiLoader.local({ baseUrl: "http://localhost:9500" })

​
Not authorized (401)

Error (gateway response): {"error":"Not authorized","status":401} Cause: Your AGENTMARK_API_KEY is missing, revoked, or doesn’t match the X-Agentmark-App-Id / AGENTMARK_APP_ID you sent. Solution:
  1. Verify the key in the AgentMark Dashboard.
  2. Make sure the app ID matches the key’s scope (keys are app-scoped).
  3. Update your .env: 
    AGENTMARK_API_KEY=sk_agentmark_...
AGENTMARK_APP_ID=app_...
  4. Restart your application so the new values are picked up.

​
Model registry

​
Model not registered

Error (TS SDK): No model function found for: 'gpt-4o'. Register it with .registerModels() or use provider/model format with .registerProviders(). Cause: The model name in your prompt frontmatter isn’t registered in your client. Solution (TypeScript): 
const modelRegistry = new VercelAIModelRegistry();

// Option 1: register providers, then use "openai/gpt-4o" in prompts
modelRegistry.registerProviders({ openai });

// Option 2: register a specific model
modelRegistry.registerModels(["gpt-4o"], (name) => openai(name));
Solution (Python): Python adapters don’t ship a default registry — you must register explicitly: 
model_registry = PydanticAIModelRegistry()
model_registry.register_models(
    ["gpt-4o"],
    lambda name, opts=None: f"openai:{name}",
)

​
registerModels array of regex rejects at type-check

Error: Type 'RegExp' is not assignable to type 'string'. [TS2322] Cause: registerModels accepts string | RegExp | Array<string> — an Array<RegExp> is not a valid overload. Solution: Wrap the regex directly, without the surrounding array: 
// Wrong
modelRegistry.registerModels([/^gpt-/], (name) => openai(name));

// Right
modelRegistry.registerModels(/^gpt-/, (name) => openai(name));

​
AI SDK v5 tool fails type-check

Error: No overload matches this call. [TS2769] on a tool({ parameters: z.object(...) }) call. Cause: AI SDK v4 used parameters:; v5 renamed it to inputSchema:. Solution: Use inputSchema: in v5 projects: 
const weatherTool = tool({
  description: "Get weather for a location",
  inputSchema: z.object({ location: z.string() }),
  execute: async ({ location }) => `Weather in ${location}: 72°F`,
});
Mastra continues to use the ai v4 tool() helper with parameters: — see Mastra integration.

​
MCP servers

​
MCP server not registered

Error (TS AI SDK adapter): MCP server 'docs' not registered. Available servers: ... Cause: The prompt references mcp://docs/... but no server named docs is configured on createAgentMarkClient. Solution: Add the server to your client config: 
export const client = createAgentMarkClient({
  loader,
  modelRegistry,
  mcpServers: {
    docs: { url: "https://example.com/mcp" },
  },
});

​
Claude Agent TS uses camelCase mcpServers, Python uses snake_case

The TypeScript adapter reads mcpServers (camelCase); the Python adapter reads mcp_servers (snake_case). The wrong casing is silently ignored — no tools will be available from the MCP server at runtime.

​
Prompts and files

​
File not found

Error (CLI run-prompt): File not found: /absolute/path/to/prompt.prompt.mdx Cause: The path passed to run-prompt doesn’t resolve to an existing file. Solution: Pass a path relative to your project root (e.g. agentmark/greeting.prompt.mdx).

​
Pre-built prompt not found

Error (FileLoader): Pre-built prompt not found: /path/to/dist/agentmark/greeting.prompt.mdx.json. Run 'agentmark build' to compile your prompts. Cause: FileLoader reads compiled JSON from the --out directory of agentmark build. The prompt either hasn’t been built or the output directory doesn’t match. Solution: 
npx agentmark build --out dist/agentmark
Then make sure your FileLoader points at the same directory: 
const loader = new FileLoader("./dist/agentmark");

​
agentmarkPath / breaks build

Error: AgentMark directory not found: /agentmark. Check your agentmark.json configuration. Cause: "agentmarkPath": "/" in agentmark.json resolves to the filesystem root. The scaffolder writes "." — the relative path from the project root. Solution: Change agentmark.json: 
{
  "agentmarkPath": "."
}

​
Invalid YAML frontmatter

Error (from the YAML parser): end of the stream or a document separator is expected (2:12) — line and column vary by the issue. Cause: Frontmatter YAML syntax error — missing space after :, incorrect indentation, unquoted strings with special characters. Solution: 
# Wrong — no space after colon
model_name:gpt-4o

# Right
model_name: gpt-4o

# Wrong — lost indentation under the parent key
text_config:
model_name: gpt-4o

# Right
text_config:
  model_name: gpt-4o

​
Unterminated TemplateDX expression

Error: Unexpected end of file in expression, expected a corresponding closing brace for '{' Cause: An open { or tag without its matching close. Solution: Verify every {expression} has a closing } and every <Tag> has its closing </Tag>. See TemplateDX syntax.

​
Datasets and experiments

​
Dataset file not found

Check that the dataset: path in your prompt’s test_settings resolves from the prompt file’s directory: 
test_settings:
  dataset: ./datasets/test.jsonl
If the file exists but the path is wrong, the error surfaces as ENOENT from Node’s fs.createReadStream. The fix is to correct the relative path.

​
Invalid JSONL

Each line must be a complete JSON object: 
{"input": {"name": "Alice"}, "expected_output": "Hello Alice"}
{"input": {"name": "Bob"}, "expected_output": "Hello Bob"}
Validate with cat dataset.jsonl | jq -c '.' — any line it can’t parse is the broken one.

​
Types

​
Props don’t match prompt input

When createAgentMarkClient<AgentMarkTypes>() is typed, TS flags prop shape mismatches. The generated types reflect the prompt’s input_schema frontmatter — regenerate after editing: 
npx agentmark generate-types --root-dir ./agentmark > agentmark.types.ts

​
CLI

​
agentmark command not found

Error: command not found: agentmark Solution: Use npx (the CLI doesn’t need a global install): 
npx agentmark dev
npx agentmark run-prompt path/to/prompt.prompt.mdx
If you want the shorter form, add a script to package.json: 
{
  "scripts": {
    "dev": "agentmark dev"
  }
}

​
Port already in use

Error: EADDRINUSE: address already in use :::9418 Solution: Use a different port, or kill the existing process: 
npx agentmark dev --api-port 9500

# or find and kill the holder
lsof -i :9418
kill -9 <PID>

​
Disable CLI update banner

Set AGENTMARK_NO_UPDATE_NOTIFIER=1 in your environment to suppress the version-upgrade banner.

​
Still having issues?

  1. Ensure your packages are current: 
    npm update @agentmark-ai/cli @agentmark-ai/ai-sdk-v5-adapter
  2. Open an issue on GitHub with the exact error string, your SDK version, and a minimal reproduction.

​
Have Questions?

We’re here to help! Choose the best way to reach us: