AgentKit Studio
Help

Help

Which page to open when something breaks, and what information to include so an issue can be triaged in one pass.

The rest of the documentation explains how things work. This chapter explains what to do when they don't.

Three routes

Your situationGo to
"Is this how it is supposed to behave?"FAQ
An error code appeared, or an operation keeps failingTroubleshooting
"This isn't a bug, you just haven't built it"Known limitations

Find your stage

Where you got stuckStart hereCommon error-code prefixes
Cannot install or openInstallation → Known limitations—
Opens but nothing worksStart checks on the OverviewHOST_CONNECTION_MISSING, STUDIO_HOST_INCOMPATIBLE
Cannot configure a modelTroubleshooting · Models & credentialsMODEL_*, CLOUD_CREDENTIALS_MISSING
Cannot create an AgentTroubleshooting · Agents & buildsAGENT_*, BUILD_*, STUDIO_PRESET_*
Sending a message does nothingTroubleshooting · RuntimesNATIVE_ENGINE_*, RUNTIME_*, DSH_TURN_FAILED
Cannot bind a resourceTroubleshooting · ResourcesMCP_*, SKILL_*, MANAGED_RESOURCE_*
Deployment failsTroubleshooting · Cloud & deploymentCLOUD_*, DEPLOYMENT_*
Session history looks wrongTroubleshooting · Sessions & historySESSION_*, STUDIO_LEGACY_HARNESS_RETIRED

Do these three things first

Before reading further, these three steps resolve most problems:

Run start checks

Overview → Start checks runs three checks and reports three states (src/client/state/start-checks.mjs:22-26):

ResultMeaning
ConfirmedReal configuration was read
MissingDefinitely not configured; follow the prompt
UnknownUnreadable (timeout / connection failure) — not "not configured"

Each check has an 8-second timeout. If all three are "unknown", the host is not connected at all — fix the connection first.

Confirm the versions

Settings → AgentKit Studio → Version and updates shows three version numbers (src/client/pages/studio-settings.mjs:78-80):

  • AgentKit Studio version — the desktop app
  • Studio plugin version — product features and runtime adaptation layer
  • DSH host compatibility version — the pinned host baseline

These are three different things. Include all three in any issue.

Reproduce once

Restart Studio and reproduce from a clean state. If it only happens "after a few turns", it is most likely session history or runtime state — note which turn it was.

What an issue needs

An issue without details only costs a round trip. Provide:

InformationWhere to get it
All three version numbersSettings → AgentKit Studio → Version and updates
Platform and architecturemacOS (Apple Silicon) / Windows (x64)
The exact error codeThe card's error text, or a trace under observability
Reproduction stepsWhich panel, what you clicked, what you typed
Operations recordsOperations → Observability → the matching trace's spans and events
Local or cloudLocal host, or a cloud managed runtime

Never paste credentials

Redact API keys, AK/SK pairs, cookies and private addresses from screenshots and logs. Studio automatically replaces common credential shapes in history with [redacted credential] (src/dsh-history-display.mjs:10-21), but screenshots and terminal output are not covered.

Self-check commands

For plugin or source installs:

# Plugin form: confirm the host version
dsh --version

# Source form: run the gate
pnpm install --frozen-lockfile
make check

# Check whether Node meets the security baseline
node scripts/check-node-version.mjs

make check covers syntax, portability, source size, contracts and product-surface checks (Makefile:71-72). When it fails, the path it prints is where the problem is.

On this page