> ## Documentation Index
> Fetch the complete documentation index at: https://studio.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot CLI workflows

> Diagnose endpoint, authorization, import planning and transfer failures.

Start with `flex-studio --help`, then run the same import using `--dry-run --json`. A planning failure can be investigated entirely on the local machine.

| Message or symptom | Action |
| - | - |
| Missing endpoint or token | Configure `FLEX_STUDIO_URL` and `FLEX_STUDIO_TOKEN` for the current process. Dry runs work without either. |
| Unknown command or option | Compare the invocation with [command reference](https://studio.bjanczak.com/cli/reference.md). |
| Workspace or entry must be a ULID | Use the public Studio ID and check copied whitespace. |
| HTTP 401 or 403 | Check token expiry, managed tool grants, workspace allowlist and actor permissions. |
| MCP tool reports a failure | Verify that tool's inputs, feature configuration and migrations using [MCP troubleshooting](https://studio.bjanczak.com/mcp-troubleshooting.md). |
| Largest resolution is ambiguous | Mark the intended original in the [manifest](https://studio.bjanczak.com/cli/manifests.md). |
| Different aspect ratios | Mark an explicit source so the retained crops are deliberate. |
| Relative path or regular-file error | Use nonempty files inside the import directory and supported relative components. Check for symlinks. |
| Directory grouping limit reached | Use a streamed JSONL manifest for the large flat directory. |
| Local file changed after planning | Freeze the source directory and repeat the dry run before importing. |
| Bundle exceeds ordinary upload limit | Use rebuild mode or adjust the host's ordinary upload policy. |
| Source exceeds ordinary upload limit | Configure [resumable sessions](https://studio.bjanczak.com/upload-resumable.md) on the host. |
| Unknown transport or invalid chunk size | Verify that CLI and server versions implement the same upload contract. |
| Direct storage PUT fails | Check role permissions, checksum support and signed endpoint reachability. [S3 multipart](https://studio.bjanczak.com/upload-s3-multipart.md) |
| Download fails to publish | Check existing output, directory permissions, space and hard-link support. |
| Search returns no files | Check workspace scope, visibility and [search indexing](https://studio.bjanczak.com/search.md). |

The client records transient transfer failures as HTTP status or timeout messages. For server-side validation details, correlate the failed operation with private application logs. If a retry succeeds for some groups, keep their results and correct the remaining inputs before continuing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.