FAQ & Troubleshooting

"It worked on my old laptop, now protect/run fails on my new one"

By default, an encrypted artifact is locked to the machine that created it — moving to a new machine doesn't move the lock. Activate the new machine (it happens automatically on your next protect/build) and re-encrypt from there. If you need one artifact to run on several machines you don't control ahead of time, use a portable artifact instead — see Encrypting Code.

"VaultLockedError on the same machine that made the artifact"

This means either the machine's identity changed enough to look like a different device (a major OS reinstall, some virtualization/cloning setups), or the local vault file was moved or altered. See Security Model for why MagicLock can't tell you which. Re-run magiclock activate to re-provision the machine.

"Can I run a .pya without installing the SDK?"

You need magiclock installed to run it (magiclock run app.pya) — but nothing beyond that. No account, no login, no network. Whoever runs your shipped app only needs the package installed, not an account with you.

"A .pya built on Python 3.12 won't load on 3.13"

Expected — see the compatibility note in the API Reference. Re-run protect/build on the new interpreter version rather than carrying one artifact across Python versions.

"What happens to already-shipped apps when my subscription lapses?"

New encryption stops working until you renew — magiclock protect/build will fail with a subscription error. Artifacts you already produced and shipped keep decrypting and running exactly as before; decryption never checks your subscription status. See Account & Activation.

"How do I deprovision a lost or retired machine?"

magiclock deactivate   # run on the machine itself, or via the account portal

This frees the seat and stops that machine from encrypting anything new under your account. It does not reach into artifacts that machine already produced — see Account & Activation for why.

"CI fails with NotLoggedInError / NotActivatedError"

Interactive browser sign-in doesn't work on a headless runner. Mint a token from your account portal and pass it non-interactively:

export MAGICLOCK_TOKEN=<token-from-your-account-portal>
magiclock protect app.py

See Account & Activation.

"protect/build fails with no network at all"

You get a 12-hour grace window since your last successful check-in before encrypting is blocked — see the table in Account & Activation. If you've never successfully activated online, there's no grace to draw on; connect once to establish it.

Still stuck?

Run the failing command again with --help for the exact flags available (magiclock protect --help, etc.), or reach out through your account portal's support channel.