Troubleshooting

Common issues related to Mudabbir’s security and credential subsystems.

”Failed to decrypt secrets.enc” Warning

WARNING  Failed to decrypt secrets.enc (machine changed? corrupted?): .
         Starting with empty credential store.

This means Mudabbir cannot decrypt ~/.mudabbir/secrets.enc — the encrypted credential store. Mudabbir will still start, but all stored API keys and tokens will be unavailable until you re-enter them.

How the Credential Store Works

Mudabbir encrypts API keys and tokens using Fernet symmetric encryption. The encryption key is derived from three machine-specific values:

Hostname — platform.node()
MAC address — uuid.getnode()
Username — os.getlogin()

A random salt is stored at ~/.mudabbir/.salt and combined with the above to derive the key via PBKDF2. If any of these values change between when the file was written and when it’s read, decryption fails.

Common Causes

Cause	Example
Hostname changed	Renamed your machine, moved to a new host
MAC address changed	Different network adapter active, VM restart with dynamic MAC
Username changed	Running under a different user account, or `os.getlogin()` returns differently in some shells vs. systemd
Salt file deleted or corrupted	`~/.mudabbir/.salt` was removed independently of `secrets.enc`
File copied from another machine	`secrets.enc` is bound to the machine that created it
Docker/VM rebuild	Container or VM got a new hostname or MAC

Fix

Delete both the encrypted store and its salt so they get recreated together on next startup:

rm ~/.mudabbir/secrets.enc ~/.mudabbir/.salt

Then restart Mudabbir. A fresh salt and encryption key will be generated automatically.

Warning

Deleting these files means all previously stored API keys and tokens are lost. You will need to re-enter them through the dashboard settings, environment variables, or config.json.

Info

Deleting only secrets.enc without .salt may not fix the issue — if the salt was created under a different machine identity, the new secrets.enc will be encrypted with a mismatched key and fail on the next read.

Prevention

Avoid changing your hostname after initial setup, or re-enter credentials afterward.
Pin MAC addresses in VMs and Docker containers to prevent identity drift.
Use environment variables (MUDABBIR_ANTHROPIC_API_KEY, etc.) as a fallback — they are always read regardless of the credential store.
When running under systemd, ensure the service runs as the same user that created the credentials. The os.getlogin() call can return different values in service contexts vs. interactive shells.

API Keys Not Loading

If your API keys seem to vanish after restart but there’s no decryption warning:

Check environment variables

Environment variables (MUDABBIR_*) always take precedence over stored values. If an env var is set to an empty string, it overrides the stored key with nothing.

Check config.json

Secret fields are stripped from config.json during save (they go to secrets.enc instead). If you manually edited config.json to add an API key, it will be migrated to the encrypted store on first load and removed from the JSON file.

Verify the migration marker

The file ~/.mudabbir/.secrets_migrated indicates that plaintext keys have already been moved from config.json to secrets.enc. If you delete this file, migration will re-run on next startup — useful if you’ve manually added keys back to config.json.

File Permission Issues

Mudabbir enforces strict permissions on credential files:

File	Expected	Purpose
`~/.mudabbir/`	`700`	Config directory
`~/.mudabbir/config.json`	`600`	Settings (non-secret)
`~/.mudabbir/secrets.enc`	`600`	Encrypted credentials
`~/.mudabbir/.salt`	`600`	Encryption salt

If files have wrong permissions (e.g., after restoring from a backup), run:

chmod 700 ~/.mudabbir
chmod 600 ~/.mudabbir/config.json ~/.mudabbir/secrets.enc ~/.mudabbir/.salt

Or use the built-in security audit with auto-fix:

mudabbir --security-audit --fix

Docker and Container Environments

When running Mudabbir in Docker, the machine identity (hostname + MAC) changes on every container restart by default. To keep credentials stable:

services:
  mudabbir:
    hostname: mudabbir          # Pin hostname
    mac_address: "02:42:ac:11:00:02"  # Pin MAC address
    volumes:
      - mudabbir-data:/home/app/.mudabbir  # Persist config directory

Alternatively, pass all secrets as environment variables so the credential store isn’t needed:

environment:
  MUDABBIR_ANTHROPIC_API_KEY: "sk-ant-..."
  MUDABBIR_OPENAI_API_KEY: "sk-..."

Last updated: February 21, 2026

3 min read

Edit this page

Was this page helpful?