Troubleshooting

Signing in

Sign-in is refused

Portal is open to anyone with an active Clusy account and a verified email address. Check that your Clusy account is active and its email address verified, then sign in again.

"Confirm it's you: this needs a Clusy sign-in from the last 5 minutes."

The action needs a fresh sign-in (reauth_required). Confirm in the console when it asks; the action goes ahead after that.

"Too many" requests, 429

You hit a rate limit (rate_limited). Wait the seconds Retry-After names, then try again.

The browser does not open for portal login

Use portal login --no-browser to print the approval page and open it on any device, or portal login --device to approve with a code.

Connecting

"verification timed out after 60s"

The provider did not answer Portal's check within 60 s. The previous connection, if any, is kept. Try again; check that the credentials work with the provider's own CLI.

portal connect modal --from-cli says the Modal SDK is not installed

The CLI as installed does not include it. Connect Modal from the console's Connect page, or with portal connect modal --file modal.env. See Modal.

Running

"No capacity is available for the requested machine right now."

No offer could start a machine (exit code 4). Run portal prices with the same requirements and pick another offer, region or provider, check your quota, or retry later. See Quotas and capacity.

The upload is refused, or files are missing on the machine

A project over 500 MB is refused; files over 100 MB and credential files are left out. Add a .portalignore with a ! rule for a file you need, and keep large data where your script downloads it. See what is uploaded.

"run has no directory to upload from"

The MCP server started in your home directory or the filesystem root and has no --root. Add --root /path/to/project to its entry in your coding tool, or run portal setup from your project. See Set up your coding tool.

A Python version is refused

Jobs run on Python 3.12, 3.13 or 3.14. Fix .python-version to one of them.

"this token may not do that (it needs the jobs scope)" on a run with secrets

The token behind the request has read access only. A run that names a stored secret (portal run --secret NAME, the MCP tool run with secrets) needs a token with the jobs scope: a CLI login or a coding tool's token has it. Each use is recorded as an event by name, never by value: the request when the job is submitted and the injection when it starts. Until 2026-11-02 this sentence named the admin scope and refused every CLI and coding tool; see Known issues.

Azure Container Apps offers show as unavailable

Container Apps offers are unavailable while the subscription has not registered Microsoft.App and Microsoft.OperationalInsights (portal connect azure --from-cli registers them, which can take up to 5 minutes), and a job's pull of the node image can be refused: Portal copies the image into a registry in your subscription and, failing that, runs the public image. See Azure.

"Constraint constraints/compute.vmExternalIpAccess violated"

Your Google Cloud organization denies VMs external IPs, so Google Cloud refused Portal's VM. Portal reads that policy when you connect, and a launch it refuses says so: the connect output, or the job's events (portal explain JOB), give the exact commands. Create a Cloud Router and Cloud NAT in the connection's region and connect again with portal connect gcp --from-cli --private-network, or ask an organization policy administrator to allow external IPs on the project. Until then Portal tries the job's next offer. See External IPs.

"the subscription cannot make Azure VMs yet"

Your subscription has never registered Microsoft.Compute or Microsoft.Network, and Portal's connection, which may change only the resource group soma, cannot register them. Run portal connect azure --from-cli again, or ask an owner of the subscription to run az provider register --namespace Microsoft.Compute and az provider register --namespace Microsoft.Network. Until then Portal tries the next offer.

Jobs that stopped or paused

The job is suspended

A spot notice, an out-of-memory rescue, a provider's time limit, its budget, a connection's cap or idleness suspended it. portal explain JOB says which. Resume it when you are ready: portal resume JOB, with --on SPEC or requirements for another machine.

"the job spent $X of its $Y budget"

A resume or a move was refused because the job's budget is spent. Raise the budget, then resume.

A machine is refused for a connection's cap

The message reads <connection>: spent $X, committed $Y, this resource could add $Z, cap $C. Raise the cap, or choose a cheaper offer. See Spend caps and budgets.

"the checkpoint expired"

A suspended job was not resumed before its checkpoint expired (3 days after the suspension by default), so it failed. Run the job again.

Outputs and logs

portal pull is refused

The job has not ended yet. Wait for it to end, or stop it: stopping a running job saves its outputs.

"the saved workspace expired" or "log expired"

Outputs are kept 7 days and logs 30 days. See Checkpoints and retention.

On Windows

"portal does not run on Windows itself: run this command in WSL."

Install and run Portal inside WSL.