Get unstuck
Find a way forward
Practical fixes for sign-in, client permissions, queued work, failed runs and file transfers.
On this page
Sign-in or client connection fails
| What you see | Try this |
|---|---|
| Invitation required | Check the Matilda account. Contact your research administrator or request a call with Maincode. |
| Identity link required | Contact your administrator to review and link your existing workspace identity. Signing up again does not restore an existing workspace. |
| Access disabled | Contact the team to review access. A fresh sign-in does not override an account decision. |
| Sign-in expired or invalid state | Start a fresh sign-in in the same browser and complete it promptly. |
| Matilda sign-in failed | Start a fresh attempt. A callback’s one-use code cannot be reused by refreshing. Send support the time and visible message if this repeats. |
| 401 or authorization_required | Refresh a token that expired after 15 minutes. If refresh returns invalid_grant with expired, rotated or revoked_by_user, authorize a fresh connection in the browser. |
| 403 or insufficient_scope | Approve the required permissions through your client’s OAuth reconnect flow. Read-only grants cannot submit jobs or edit files. |
Use the exact /mcp/research server URL for researcher tools. If the client remains disconnected, inspect its MCP output log and check whether it supports remote HTTP with OAuth and PKCE.
Work is waiting or will not submit
- Read research_run or research_job for the original job’s state and reason.
- Check research_profile and validate a smaller resource request if the policy or capacity is exceeded.
- Finish or cancel an existing job if you have reached a running or submitted-job limit.
- Keep a queued job while it waits. Retry a timed-out submission using the same UUID request ID and arguments.
If the service cannot reserve a workspace for your account, contact your research administrator or Maincode. A storage allowance still needs available capacity to be provisioned; changing a job’s CPU or GPU request does not resolve that storage reservation.
A training run failed
| Symptom | Next step |
|---|---|
| Nonzero exit code | Read stderr with research_logs and review the input and script. For a new codebase, confirm imports and the launch command in a small interactive allocation before another batch submission. |
| Out of memory | Reduce the workload or request more memory within policy. |
| Timeout | Inspect a saved checkpoint and resume with a suitable time request. |
| Missing file or changed input digest | Check exact paths and SHA-256; relative paths begin at /workspace. |
| Missing software or failed network access | Check research_profile for the active network mode. Use matilda-venv to install persistent packages; private networks and non-HTTP ports are blocked. |
| No metrics yet | Write complete JSON objects followed by a newline into MATILDA_RUN_DIR/metrics.jsonl and flush the file. |
| A checkpoint cannot resume | Use a finished owned parent, a checkpoint under its run directory and a script that loads MATILDA_CHECKPOINT. |
A native completed state still needs scientific verification. Inspect outputs and metrics to confirm the program produced the expected result. Make failure handling explicit in your script.
A file operation or transfer fails
| Problem | Recovery |
|---|---|
| File version or SHA-256 conflict | Read the current file and review it before replacing or deleting. |
| Chunk offset conflict | Read research_transfer_status and continue from its accepted offset. A retried chunk must contain identical bytes. |
| Final digest mismatch | Abort the transfer and recheck the local file’s complete size and SHA-256. |
| Storage limit / Disk quota exceeded / No space left on device | Remove reviewed files or abort unused transfers. Replacement needs temporary space for both versions. |
| Inline size limit | Use resumable HTTPS transfers for datasets and large files. |
| Unsafe path or symlink | Use a regular file under your workspace with a relative path and no traversal. |
| Download version changed | Restart from the current ETag and verify the final digest. |
| Transfer expired | Start a new transfer. Published files remain available after transfer receipts expire. |
Send a useful support report
Contact hello@maincode.com or your research administrator. Include the details below and relevant output. Keep passwords, tokens, cookies and sign-in callback URLs out of the report.
Research email:
What I was trying to do:
Run, job or transfer ID:
Native state and reason:
Requested CPU / memory / GPUs / time:
UTC time of the issue:
API request ID, if available:
Exact error and relevant output:
Client and steps to reproduce: