Troubleshooting By Symptom | IDEAL IT Passport

Choose the symptom, not the technology you think caused it.

A real leak, lost data or uncontrolled job: use the private incident route now.
Waiting for an automatic lesson check: keep the submitted attempt; after 30 minutes, use one public help request with its public PR URL. Do not submit duplicates.
A command or local check failed: find the matching symptom below and follow only that recovery.

git is the program that records file history. gh is GitHub CLI, the program used to work with GitHub from text commands. Blade is the lab's shared remote Windows computer; Euler is ETH Zurich's shared service for research calculations.

Unless a row explicitly says Euler or Blade, run gh and git commands on your own computer. If terminal, shell, PowerShell, zsh, or Bash is new vocabulary, first read Terminal And Command Basics if needed. It shows which application to open and where to paste a command; return to the symptom you were resolving afterwards.

Already started on another computer? Follow Continue On Another Computer to keep the same Passport.

Access And Authentication#

gh passport start cannot create or find your learning record: run gh auth status and confirm that it names the GitHub account you intend to use. Then run gh passport doctor. Do not clone the exercise repository by hand or create an organization repository.
On an Apple Silicon Mac, Update and reopen restores the previous launcher instead of completing: versions through v0.5.4 can reject GitHub CLI's valid macOS installation. Do not delete or recreate the Passport. Run this one-time launcher update from Terminal only if that old-version failure matches your case, then reopen the same Passport:
```
gh extension install soheylm-passport-sandbox/gh-passport --force --pin v0.12.1
gh passport version
gh passport open
```
The version output must contain 0.8.0. It reports curriculum 5.0.0 for a new course, or the assigned 2.1.2, 3.0.0, or 4.0.0 inside an existing Passport. This replaces only the launcher; local progress and public submissions remain unchanged.
The dashboard still reports an old rollback after a successful manual installation: run gh passport version. Version v0.5.7 ignores rollback records written by an older launcher. Run gh passport open again; do not delete, purge, or restart the Passport.
GitHub clone asks repeatedly for credentials: use the authentication section of the Git guide.
Euler SSH timeout: connect to ETH VPN and check Euler status.
Euler password works but SSH key does not: follow Euler SSH troubleshooting.
UNPROTECTED PRIVATE KEY FILE: inspect which file is named; a .pub filename usually means IdentityFile is wrong.
Tunnel asks for ETH password: make the final public-key-only config-ok alias test pass before troubleshooting the tunnel or VS Code.

Git And Code#

The Passport check reports controller_configuration: do not delete the Passport, change unrelated files, or recreate either PR. This is a controller error, not a failed exercise. Wait for the next automatic check. If it remains after 30 minutes, open one Passport help request with the public PR URL and the check name only.
Wrong files staged: git restore --staged <path> keeps the edit but removes it from the staged diff.
Secret committed: revoke it immediately and notify the repository owner.
Push rejected: fetch and inspect remote changes; do not force-push a shared branch without explicit coordination.
Python works only in one old environment: recreate from declared dependencies and record what is missing.

AI Coding Agents#

Copilot Student asks for payment or is unavailable: verify the GitHub Education account. Continue other assigned tracks while access is pending; manual work does not pass the AI-tool setup lesson. Payment is not required.
Zed keeps using an old OpenRouter key: inspect local OPENROUTER_API_KEY precedence before replacing keychain settings.
Agent changes too much, forgets constraints, reports unproven tests, or spends unexpectedly: stop the session and use the AI agent troubleshooting guide.

Euler Jobs#

Job pending: inspect myjobs -j <job-id> and the squeue reason; do not submit duplicates.
Job fails immediately: inspect logs and sacct state/exit code.
Out of memory: inspect application behavior and MaxRSS before changing memory.
GPU allocated but idle: inspect device placement, CPU/data loading, and I/O before adding GPUs.
Array starts too much work: cancel the parent job and add a low % cap.
ParaView GUI does not connect: use matching local ParaView 6.0.0, download a fresh ETH euler_600.pvsc, and follow the ParaView recovery steps.

See the full Euler troubleshooting guide.

Storage And Permissions#

NAS path not found: confirm VPN, supervisor first name, and exact assigned folder.
Euler quota failure: run lquota and inspect both capacity and file count.
Shared folder not writable: inspect ls -ld, getfacl, and id; ask the data owner to repair the specific folder.
Important file was in scratch/Blade D: only: report possible data loss and restore from the main approved copy.

Ask For Help Safely#

For an ordinary technical blocker, open one public Passport help request. The queue is asynchronous: submit once and return later. Nobody needs to be online while you submit it.

Use this template in the form:

Operating system:
Machine and shell where command ran:
Guide and section followed:
Command with private information removed:
Exact error:
Expected result:
Checks attempted:

Replace secrets and confidential values with <redacted>. Never attach an SSH private key, password, token, recovery code, .env, or protected dataset.

Do not use the public form for a real incident, a real NAS path, an ETH username or email address, or confidential project details. Use the private route in Incidents And Getting Help instead.