Developer docs
Troubleshoot API, CLI and MCP connections
Resolve sign-in, permission, schema, upload and uncertain-write failures without exposing credentials or duplicating accepted work.
Read as MarkdownReviewed by SosoAPI team ·
Wrong browser or blocked local login
Stop the pending login, then run auth login --no-open. Open the newly printed URL in the browser profile you want to use. Check the account and workspace before granting access, and use only one browser profile for that login link. If port 8789 is busy, identify the listener and stop it only if it is a login process you started.
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401, 403 and unavailable accounts
For 401, check that you are signed in with a current credential. For 403, check the workspace role, selected scope and capability required for the operation. Use auth status and verify the account’s email and accepted credential type. Change access only if that operation needs it; switching the tool profile will not grant permission.
Check the social account separately. Read its connection and capabilities, and reconnect only if the provider needs renewed consent. An internal service error is not a reason to recreate a healthy connection.
400 validation and version skew
Read the response body and validation field paths. Validation errors may contain a ZodError; handler errors may use error, message and code fields. Compare the request with the installed contract and update your client’s package if needed. Fix the fields named in the error without removing required values or adding unsupported filters.
npx sosoapi api contract --route /studio-api/scheduled-posts/409, 429, 5xx or a timed-out write
For 409, read the latest resource version and available actions before changing it. For 429, wait as directed by Retry-After and reduce concurrency. If a write times out or returns 5xx, keep its ID and check the existing result first: the server may have accepted it before the connection failed.
Retry only when that operation and its current state allow it. Keep the same key for the same payload, and do not create a replacement to bypass an uncertain result. Fix authentication failures before retrying. If a background job is still pending, its status can already contain an execution error worth checking.
Upload or tool-discovery problems
Local upload accepts supported media files up to 500 MiB from the working directory, the temporary folder, Pictures/Movies/Videos or folders listed in SOSOAPI_UPLOAD_ROOTS. Dot-folders and symlinks that escape those roots are refused. Add the specific media folder you need rather than your whole home directory. An HTTP connection cannot read local files.
If tools are missing, reconnect the client and compare its profile and connection type with the reference. Check that the tools are loaded in the current conversation; a saved server name alone does not confirm that.
Share useful diagnostics safely
Share the operation name, time, HTTP status, safe error code and request_id or x-request-id if one is available. Include the CLI version and whether you used local or remote MCP. Remove tokens, cookies, authorization links, signed media URLs, customer content and private IDs. Share the relevant error rather than a credential file or an entire response.