Skip to main content
Start with the symptom below. If it is still unclear, send a minimal reproduction to ugurlu.oozgur@gmail.com or open an issue.

​
The runtime cannot be found

The local runtime is installed through an optional npm dependency. Confirm the SDK is installed in the project where you run the script:
Use Node.js 22+ and a supported platform. Reinstall with optional dependencies included:
Do not copy node_modules between operating systems or CPU architectures. In a minimal container without a local runtime, use remote mode.

​
The model rejects my API key

  1. Confirm that the key belongs to the provider in model. An OpenAI key goes with an openai/... model.
  2. Load the key in the process that runs the agent. With a .env file, use node --env-file=.env agent.mjs.
  3. Check that your provider account has access to the selected model and available quota. Installing the SDK does not grant provider access.
  4. If you use a custom environment-variable name, pass it through spawn.auth; see runtime defaults.
Check whether a key is present without printing its value:
Your personal runtime login files are not automatically used by the isolated SDK runtime. The quickstart uses an explicit provider API key.

​
A model or option is unavailable

A model ID has the form provider/model. The SDK’s typed catalog offers completion; it does not prove that your provider account can use every entry. Verify the provider’s model access and use a model you can call. If an effort or thinking setting is rejected, remove that optional setting first. Model features differ across providers. See models and prompts.

​
The agent cannot use a tool

Check these in order:
  1. Availability: use the correct ID from built-in tools. Some tools depend on the model or runtime configuration.
  2. Selection: a nonempty allowedTools list limits the tool inventory. Custom tools are exposed as sdk_<name>.
  3. Denials: remove the quickstart’s disallowedTools: ["*"] when enabling tools. An empty allowedTools array does not disable tools.
  4. Permissions: a selected tool may still need approval. Review server permission rules and your permissionMode.
  5. Callback: validate custom tool input inside execute; the schema describes the tool but does not replace your validation.
Use permissions and the custom-tool cookbook for complete examples.

​
A run waits for permission

An ask decision needs an application that can respond. For unattended jobs, choose a policy that returns concrete allow/deny decisions and rejects unresolved prompts. canUseTool handles unresolved approvals, not every tool invocation. A callback timeout can leave a permission request waiting; it is not an automatic denial. Avoid enabling the interactive question tool unless your application implements the corresponding input flow. See permissions and cancellation.

​
A run returns an error without throwing

Setup and connection errors can throw. A completed model run can instead return isError: true and a terminal subtype, such as error_max_turns or error_aborted. Check both channels:
Use kind for SDK setup/lifecycle errors and subtype for terminal run outcomes. See SdkError and RunResult.

​
Structured output is missing

Check the terminal result before reading structured data. The model must support the required tool/output behavior, the response must fit its output limit, and the StructuredOutput tool must remain available. A wildcard tool denylist disables it too. Use a simple provider-facing schema and validate your application’s stronger constraints afterward. The contact extraction cookbook shows the complete pattern.

​
The script does not exit

Finish, abort, or return from active streams, and close resources you own. With the default Agent or query() runtime, call shutdown() when the whole application is done. An Agent created with explicit spawn options owns its dedicated runtime; a borrowed client must be closed by its creator. Do not call process-wide shutdown() after each request in a shared web service. See lifecycle and cleanup for complete script and service patterns.

​
A conversation loses its memory

Each agent.run() starts a new session. Use one await agent.createSession() handle for messages that should share context. See session memory. Resuming an ID requires the same backing runtime/database. The default isolated runtime’s scratch data is removed when it closes successfully. Use a persistent remote runtime for conversations that must outlive the local process.

​
Streamed text appears twice

Completed assistant messages contain full text; partial events contain increments. Display one representation for the same response instead of appending both. See streaming for the event types and examples.

​
Collect useful diagnostics

Include the SDK version (npm ls cognitio-agent-sdk), Node/Bun version, operating system and architecture, model ID, terminal subtype or SDK error kind, and a small script that reproduces the problem. session.getAppliedSettings() helps confirm resolved session configuration; review and redact it before sharing. Do not send API keys, auth headers, private files, or sensitive prompts. For a private report, use the support contact.