SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsstackbone-debug

stackbone-debug

Testing & quality

View repository

Updated 10-16 01:08

About this skill

Stackbone debug skill

This skill tells you how to locate the cause of a failure in a Stackbone workspace. It holds no error catalog: the meaning of each code, status and message lives in the docs, and you read it from there once you have the code in hand.

Where the facts live

The docs are served over MCP as the stackbone-docs server (https://docs.stackbone.ai/mcp, public, tools search_docs, get_doc, list_docs). stackbone docs prints the connection details.

  • Start the session with list_docs. It returns every page under its area and section. How to find the owner page below says which page a code or a symptom belongs to; take its path from that list and get_doc it. Never type a path from memory: pages move, titles stay.
  • Once you hold an error code, read the page that owns it: its error section says what the code means and what to check next.
  • Once you hold a message with no code, search_docs with the message verbatim, then with the symptom in plain words.
  • Do not explain a code from memory. Codes are stable but their causes and the next command change between releases.

No stackbone-docs tools in your session? Fetch https://docs.stackbone.ai/llms.txt: the same index, one line per page with its title, its description and a link to its raw markdown. Pick the page by title and fetch that link. https://docs.stackbone.ai/llms-full.txt is every page in one file (~700 KB).

How to use this skill

  1. Capture the symptom verbatim: the error message, the HTTP status, the run id, the exact command. Never paraphrase it.
  2. Get a code. Re-run the CLI command with --json and read error.code + error.suggestion; read result.error.code from an SDK call; read the status and body of an HTTP response; read the run's log frames.
  3. Run the first diagnostic from the tables below, as-is. Every command here is read-only. A mutation (retry, cancel, approve, reject) is marked ⚠️ and must be proposed to the user before it runs.
  4. Read the owner page (how to find it) for what the code means and what to check next.
  5. Report what you found with the exact command output, then hand off: a code change goes to the stackbone skill, a command or a migration to the stackbone-cli skill.

Locate a failing run

Every agent turn and every workflow run is a durable run with a status (running / done / failed / interrupted) and a log. The local-dev installation is the default target and needs stackbone dev running; pass --agent <id> (from stackbone agents list --json) for a deployed one.

stackbone runs list --status failed --json          # find the run id
stackbone runs get <runId> --json                   # header: status, trigger, timing
stackbone logs tail --run <runId> --json            # the per-step frames: each 'use step', its retries, the error that failed it
stackbone logs tail --level error --json --follow   # watch a live installation

There is no runs steps verb: the step waterfall is in the log frames. Studio's Runs tab shows the same timeline.

Symptom → first diagnostic

Symptom First diagnostic
A stackbone command fails Re-run with --json; read error.code + error.suggestion; escalate with STACKBONE_LOG_LEVEL=debug, then --verbose for a boot stage
Exit 3 with no project / dev_not_running stackbone metadata --json; is .stackbone/project.json there, is stackbone dev up
Exit 4 runtime_not_configured against --agent stackbone agents get <slug> --json: the box has no registered deployment
stackbone dev stops or nothing of yours starts Read the boot banner; the first run waits for a model provider (a Studio link is printed)
Workflow start rejected, no run created (HTTP 400) stackbone workflows schema <name> --json; compare the body to issues[] in the 400
workflow_not_found / workflows list shows nothing Is there a workflows/<name>.workflow.ts; is dev serving it
A step retries then the run fails stackbone logs tail --run <runId> --json: the recurring error.cause; is the step idempotent
Run stuck running with no progress It is parked on a requestApproval() gate: stackbone hitl list --status pending --json
Run paused but the inbox is empty stackbone logs tail --run <runId> --json for approval_persist_failed; or the pause timed out and the fallback fired
Agent turn interrupted on a gated tool; new messages rejected Expected until decided: stackbone hitl list --status pending --json → ⚠️ stackbone hitl approve <id> --yes --json
The agent forgot the conversation Did the client send x-stackbone-session; does the workspace have the checkpointer peer (the boot log warns once)
Run succeeds with no output The body returned undefined instead of an object matching outputSchema
A schedule never fires or fires twice stackbone workflows list --json; stackbone.workflows.listSchedules() from a step
stackbone.connection(id) throws Read err.code: connector_installation_required → the operator has not installed that connector in Studio; credential_error / no_token → its credential. The id is the connector's verbatim id, not a per-connection one
Storage 404 on a key just uploaded; signed URL 403 Was the upload's error checked; did the URL TTL elapse; is local MinIO up
Slow query, wrong pgvector order, empty tsvector search stackbone db schemas --json, stackbone db query "<single SELECT>" --json; EXPLAIN needs psql on STACKBONE_POSTGRES_URL
stackbone build / package aborts The message names the native dep or the second SDK copy (a nested node_modules or a per-agent pin)
stackbone.secrets.get returns secrets_not_found / _decrypt_failed stackbone secrets list --json (names only, values masked)
A model call returns nothing, 429, 402 result.error.code (ai_*); check the model provider on Studio's gateway screen

How to find the owner page

  • An SDK code (<prefix>_<reason> from result.error.code): search_docs the code verbatim with area sdk. The owner page lists it in its error table, so the top hit is the page. The prefix names the surface (ai_* → stackbone.ai, rag_* → stackbone.rag, secrets_* → stackbone.secrets, …); two do not: s3_* belongs to stackbone.storage and approval_* to Human-in-the-loop. contract_* and capability_unavailable are explained on @stackbone/sdk overview (SDK › Reference).
  • A ConnectorCallError code (connector_installation_required, credential_error, invalid_args, …): stackbone.connection (SDK › Platform), which carries the full list. Match err.code, never instanceof.
  • A CLI error.code (dev_not_running, runtime_not_configured, no_project, …) or an exit code: Troubleshooting (CLI › Guides), then Configuration reference (CLI › Reference) for the exit-code table.
  • An HTTP status from the box or the control plane: search_docs the status and the route (400 workflow_input_invalid, 404 workflow_not_found); the workflow routes live under CLI › Agent protocol. A 402 body (tier_quota_exceeded, *_cap_reached) is not an SdkError and is not retryable: surface its message verbatim; the organization owner upgrades.
  • A run you want to read after the fact: Logging & observability (SDK › Platform); a box that will not register or answer: Troubleshooting under Home › Deploy.

Three things to keep straight

  • Three surfaces throw, the rest return { data, error }. stackbone.database throws Drizzle/Postgres errors; callDeepAgent / streamDeepAgent throw and fail the enclosing step; stackbone.connection(id) throws a ConnectorCallError (match err.code, never instanceof). Everything else puts the code in result.error.code, with meta and cause as the structured escape hatches.
  • A 402 is a control-plane body, not an SDK code. The SDK-side twin of a spent credit bundle is ai_credits_exhausted.
  • A 404 on --agent <id> from another organization is expected. Studio uses the same 404 to avoid leaking existence.

What this skill does not cover

Runtime performance tuning (cold start, sizing), cost analysis beyond the 402 bodies, and custom OTel pipelines. Studio's Logs and Costs tabs are the supported surfaces for those today.

Other skills

  • stackbone: the fix, when it is code (defineDeepAgent, a step, an ambient call).
  • stackbone-cli: the fix, when it is a command, a migration or a deploy step.
  • stackbone-coder: start a new piece from a one-line idea through an interview.