Troubleshooting

System creation stalled

Symptom: During system creation, a yellow warning appears saying a stage has stalled.

What’s happening: The process monitors its own progress. If no forward movement is detected for ~2 minutes, it surfaces a warning with the stage name and offers recovery options.

Options shown in the TUI:

[w] Wipe + Retry — Best first option. Destroys the partial system and restarts clean.
[Enter] Keep waiting — Dismisses the warning. Choose this if the machine is under heavy load and you expect it to catch up.
[Esc] Cancel — Returns to the configuration screen.

There are no hard timeouts — the process never silently gives up. You always get a choice.

System not starting

Symptom: The startup step hangs or fails.

Check:

Did the preflight check pass? Run merka doctor — it verifies everything Merka needs on your machine and tells you how to fix anything that’s missing.
Do you have enough disk space? The default local system needs ~120 GB free.
Do you have enough RAM? At least 8 GB, ideally 16 GB.

Fix: Address what merka doctor reports and try again. If the system is stuck in a bad state, use Wipe + Retry from the warning prompt, or Start over / reset from the dashboard menu, then run merka again.

System not reachable

Symptom: The dashboard shows “Unreachable” or merka status can’t connect.

Check:

Is the system running? Check merka status.
Is your firewall blocking local network connections?

Fix: Relaunch merka — if the system was interrupted, you’ll get a recovery prompt with a Resume option. If it stays unreachable, use Start over / reset from the dashboard menu for a clean start.

Services stuck in Pending

Symptom: merka status shows services stuck in “Pending” state.

What’s happening: Services start in dependency order. If an early service (like storage or the database) is slow to come up, later services wait.

Fix: Wait 5-10 minutes — services usually resolve on their own. If they’re still stuck:

# Check which services are stuck
merka status

# Get detailed logs
merka diagnostics export

Identity lost

Symptom: You see the first-run screen again on a device where you previously had an identity.

What happened: The device-signing key was deleted or became inaccessible (Keychain reset, OS reinstall, etc.).

If you have your recovery file: open it, copy the recovery_key value (a string starting with MK-), and run:

merka recover

You’ll be prompted for the recovery key.

If you don’t have your recovery file: You’ll need to create a new identity and re-claim your system. Your data on the system is still there, but you’ll need to go through the claiming process again.

Recovery file location

If you’re not sure where your recovery file is:

# macOS
~/Library/Application Support/rocks.cosmic.merka.cli/recovery/merka-recovery.json

# Linux
~/.local/share/rocks.cosmic.merka.cli/recovery/merka-recovery.json

Process killed during system creation

Symptom: You closed the terminal, hit Ctrl-C, or the machine rebooted while your system was being created.

What happens: The next time you launch merka, it detects the interrupted state and shows a recovery prompt with three options:

[R] Resume — Restarts the system from its saved state and re-enters the creation flow where it left off.
[W] Wipe — Destroys the partial system and starts fresh from the device-scan screen.
[Esc] Ignore — Skips recovery and goes to the device-scan screen. The saved state stays on disk.

Activation failed

Symptom: System creation completed but activation didn’t happen (e.g. the process was interrupted right at the activation step).

What’s happening: The system is running but hasn’t been claimed by your identity yet. Normally, activation happens automatically at the end of the creation wizard. If it was interrupted, you can activate manually.

Fix:

merka activate

It activates the system you’re connected to. If it reports that no system is configured, connect first with merka connect <url> (the address is shown in merka status output), then run merka activate again.

Getting help

Check logs: merka diagnostics export creates a support bundle with all relevant logs (sensitive data redacted by default).
Run the doctor: merka doctor checks your environment for common issues.
Check status: merka status --json gives you the full system state.