Troubleshooting - CogFoundry Docs

Choose the first check

Symptom	First action
Invalid flag, local file, JSON, workbook, or TemplateSpec	Fix the reported local input; do not start with `doctor`
Authentication, endpoint, network, service-version, or unexpected server error	Run `loomloom doctor --output json`
Paid or state-changing request failed ambiguously	Query remote state before any retry

Configuration failures

If the server is missing, set a full HTTPS URL:

export LOOMLOOM_SERVER="https://loomloom.shengsuanyun.com/loom/v1"

If the token is missing or rejected, create or copy a key from the ShengSuanYun API Keys page, configure LOOMLOOM_TOKEN, and run doctor again. Never paste the real key into an issue or log. If the CLI reports a platform mismatch, stop. Verify that server and token were issued for the same platform and environment. Do not work around the check by sending the token to a different host.

Input and authoring failures

orchestration input must be a .jsonl file: use a .jsonl file for orchestration-input upload.
Missing inputFileId: preserve the exact value returned by orchestration-input upload; do not use an inputAssetId.
TS-TOPOLOGY-001: remove bindMode=expanded. Use one row per independent item or explicit fixed parallel steps connected with dependencies and upstream bindings.
Workbook validation failed: fix the reported row and field, then validate and precheck the unchanged workbook again.
Model unavailable: query model list or template-spec models against the active environment.

Run and result failures

Use:

loomloom run get <run-id> --output json
loomloom run watch <run-id> --max-wait 30m
loomloom usage get <run-transaction-id> --output json

Do not construct a run-detail URL. If an artifact signed URL has expired, retrieve current result metadata or rerun artifact download; do not store the old URL. For an identical confirmed retry after an ambiguous failure, reuse the original client request ID. If any input changed or a new confirmation was obtained, use a new ID.

Local Agent Skill failures

If a dry run returns output_dir_name_mismatch, append the returned skillName to the parent directory and run the dry run again. If the destination contains files, choose an empty directory or run an uninstall dry run. Use --force only after explicit confirmation to remove unexpected files.

Report a reproducible issue

Open an issue in the LoomLoom GitHub repository with:

CLI version
operating system and architecture
sanitized command and error
sanitized doctor --output json result
minimal non-sensitive input that reproduces the problem

Remove tokens, workbook contents, private prompts, signed URLs, and customer data before sharing.

​Choose the first check

​Configuration failures

​Input and authoring failures

​Run and result failures

​Local Agent Skill failures

​Report a reproducible issue