Skip to main content

Agent Troubleshooting

CLI is not on PATH​

Run command -v sstudio in the same shell environment that starts the Agent. If it prints no path, add the package manager's executable directory to the user shell PATH, then start a new Agent session. A Python user installation commonly places commands under the bin directory of the base reported by python -m site --user-base; on macOS this is often ~/Library/Python/<version>/bin.

Do not ask the Agent to search the filesystem for another executable, inspect credentials, or fall back to raw HTTP.

Version is incompatible​

Compare sstudio --version with the Skill manifest. In Skill 0.4.1, only the exact testedSdkVersion is approved for an enabled network capability; minimumSdkVersion does not imply that every newer version is compatible. Provide an explicit upgrade or downgrade instruction, then stop before network operations. Do not assume the latest package remains compatible with a fixed Skill release.

For msp-operations 0.4.1, restore the tested version with one applicable command:

python -m pip install --upgrade "sstudio==0.0.6"
npm install sstudio@0.0.6
npm install --global sstudio@0.0.6

No authenticated Profile​

Ask the user to run login manually. Do not open ~/.sstudio/credentials.json, ask for its contents, or try browser-session credentials. Follow Configure SDK and Authentication for the complete user-run command.

Permission denied​

Report the attempted non-secret operation and current identity when it was safely observed. Ask the environment administrator for the required role or scope. Do not switch credentials or escalate privileges.

Capability is pending or disabled​

Provide Guidance or a normalized Plan and name the missing gate, such as a Contract Test, sandbox E2E, idempotency evidence, or Agent evaluation. Do not fall back to Console automation, internal frontend APIs, or raw HTTP.

Preview fails​

Return the redacted preview decision and actionable reason. Resolve model, cluster, accelerator, recipe, Dataset, or resource specification choices from the current environment; never guess replacements.

CLI command fails​

A non-zero exit status is failure. --format json applies only to successful stdout; treat stderr as labeled text, redact sensitive values, and do not assume it is stable JSON.

Waiter times out or result is unknown​

Return the last observed state and a manual verification route. Query by a known resource ID or documented idempotency token when allowed. If neither is available, stop rather than repeat a possible mutation.