Error Messages
Reference for all error codes, their causes, and how to resolve them.
CLI Errors
Authentication Errors
| Error |
Cause |
Solution |
Authentication failed |
Invalid credentials or expired token |
Run pylocket login to re-authenticate |
Token expired |
Access token has expired |
Run pylocket login or set a fresh PYLOCKET_TOKEN |
Invalid API key |
The API key is incorrect or has been rotated |
Generate a new key via pylocket auth api-keys rotate |
2FA code required |
Account has 2FA enabled |
Enter your TOTP code when prompted |
Invalid 2FA code |
Incorrect TOTP code |
Check your authenticator app; ensure your device clock is synced |
Artifact Errors
| Error |
Cause |
Solution |
Unsupported artifact type |
File extension not recognized |
Ensure the file is one of: .py, .pyz, .pyw, .whl, .egg, .zip, .tar.gz, .tgz, .tar.bz2, or a platform executable |
Artifact too large |
File exceeds the upload size limit |
Contact support for large artifact handling |
Upload failed |
Network interruption during upload |
The CLI retries up to 3 times automatically. Check your connection and try again. |
Artifact not found |
The specified file path does not exist |
Verify the --artifact path is correct |
Build Errors
| Error |
Cause |
Solution |
Flagged by N of M AV engines (build status rejected) |
Enough of the AV engines that returned a verdict flagged the artifact |
Usually a false positive on packed Python apps. The message includes the SHA-256; Pro plans also list which engines flagged it and what each called it. See Clear an antivirus false positive. Signing your builds with your own certificate builds antivirus reputation for your future builds. A rejected build cannot be replaced; upload again once the false positive is cleared. |
Specify a Python version: PyLocket could not detect it from this artifact... |
The artifact carries no Python version marker (source-only zip, pure-Python wheel, raw script) and no version was provided |
Enter the version in the portal upload form's Python Version field, or pass --python with the CLI, then upload again. Compiled artifacts (PyInstaller, cx_Freeze, Briefcase) are detected automatically and never need this. |
Python X.Y is not supported... |
The artifact was built with a Python version PyLocket has no runtime for |
Rebuild your application with Python 3.12, 3.13, or 3.14 and upload again |
Build failed: INVALID_BYTECODE |
Python version mismatch |
Ensure --python matches the version used to build the artifact |
Build failed: NO_PYTHON_CODE |
No Python bytecode found in the artifact |
Verify your artifact contains compiled Python code |
Build failed: UNSUPPORTED_PLATFORM |
Platform token not supported |
The platform is set per-build. Re-run pylocket protect with a supported --platform token (win-x64, linux-x64, macos-arm64, macos-x64) |
Build status: FAILED |
Generic build failure |
Check the build details for a specific error message |
Code Signing and Installer Errors
PyLocket does not code-sign your app. You sign the protected build with your own certificate and upload the signed copy with Replace with Signed Package; see Code Signing.
| Error |
Cause |
Solution |
Replacement is not code-signed (...) |
The file you uploaded with Replace with Signed Package has no signature: no Contents/_CodeSignature/ in a macOS .app, or no Authenticode certificate table in a Windows .exe |
Sign the protected build with your own certificate, then upload the signed copy |
Only ready builds can be replaced (...) |
The build is not ready (for example, it was rejected or is still processing) |
Replace a ready build. A rejected build cannot be replaced; upload a new build instead |
Code-signed replacement supported for: ... |
Replace with Signed Package takes a macOS .app (including Briefcase) or a single-file Windows .exe |
A Windows build uploaded as a folder (PyInstaller onedir, cx_Freeze) cannot be replaced with a signed copy yet |
Replacement refused: the signed file is ... bytes, over the ... limit for Replace with Signed... or Replacement refused: the signed file is larger than the ... limit for Replace with Signed... |
The signed file is over the Replace with Signed size limit. Signing adds very little to a build, so this is almost always the wrong file |
Download this build again, sign it without rebuilding, and upload that signed file. If your signed app really is larger than the limit, contact support |
Replacement refused: the uploaded archive lists ... files in a ...-byte file directory... |
The .zip lists far more files than the build it replaces, so it is not a signed copy of it |
Archive the signed .app with ditto -c -k --keepParent YourApp.app YourApp.app.zip (or let pylocket replace-signed archive it) and upload that. If your signed app really has that many files, contact support |
This application has not been code-signed yet, so it cannot be installed with PyLocket Installer... (seen by your customer) |
The Windows or macOS build the Installer or Hub was asked to install has not been replaced with your signed copy |
Sign the build, upload the signed copy with Replace with Signed Package, and ask the customer to try again |
Refusing to install "...": it is not notarized ... (seen by your customer, macOS) |
The copy you uploaded is not notarized (or not signed with your Developer ID), so Gatekeeper rejects it on the customer's Mac |
Sign it with your Developer ID, notarize and staple it, and upload the notarized copy |
Network Errors
| Error |
Cause |
Solution |
Connection refused |
API server unreachable |
Check your internet connection and the API URL |
Connection timeout |
Slow network or server under load |
Retry the command. If persistent, check status page. |
SSL certificate error |
TLS verification failed |
Ensure your system certificates are up to date |
API Error Codes
HTTP Status Codes
| Code |
Meaning |
400 |
Bad request — invalid input |
401 |
Unauthorized — invalid or missing auth token |
402 |
Payment required — free tier exceeded |
403 |
Forbidden — insufficient permissions |
404 |
Not found — resource does not exist |
409 |
Conflict — duplicate resource (e.g., duplicate email) |
422 |
Validation error — request body failed validation |
429 |
Rate limited — too many requests |
500 |
Internal server error |
Application Error Codes
| Error Code |
HTTP Status |
Description |
INVALID_CREDENTIALS |
401 |
Email or password is incorrect |
ACCOUNT_DISABLED |
403 |
Developer account has been suspended |
MFA_REQUIRED |
200 |
2FA code needed to complete login |
INVALID_MFA_CODE |
401 |
Incorrect TOTP code |
APP_NOT_FOUND |
404 |
App ID does not exist or belongs to another developer |
BUILD_NOT_FOUND |
404 |
Build ID does not exist |
BUILD_NOT_READY |
400 |
Attempted to download a build that is not in READY status |
INVALID_LICENSE_KEY |
401 |
License key does not exist |
LICENSE_REVOKED |
401 |
License has been revoked |
LICENSE_EXPIRED |
401 |
License has passed its expiration date |
DEVICE_LIMIT_EXCEEDED |
403 |
License has reached its maximum device count |
VELOCITY_LIMIT_EXCEEDED |
429 |
Too many activations in a short period |
PAYMENT_REQUIRED |
402 |
Free tier downloads exhausted; subscription needed |
DUPLICATE_EMAIL |
409 |
An account with this email already exists |
VALIDATION_ERROR |
422 |
Request body failed validation (details in response) |
RATE_LIMITED |
429 |
Too many API requests |
Runtime Errors
These errors appear when the protected application runs on an end-user's machine.
| Error |
Cause |
Solution |
License activation failed |
Invalid key, revoked, or expired license |
Verify the license key is correct and active |
Device limit exceeded |
All activation slots are used |
Contact the developer to reset devices or increase the limit |
Runtime not found |
Native runtime library is missing |
Ensure all files from the protected output are distributed together |
Manifest verification failed |
Tampered or corrupted manifest file |
Re-download the protected application |
Token expired |
Offline for more than 14 days |
Connect to the internet to re-validate the license |
Analysis environment detected |
Debugger or analysis tool detected |
Close debugging tools and run the application normally |
Troubleshooting Checklist
"My protected app won't start"
- Verify all files from the protected output are present (executable, native runtime, protection manifest)
- Check that the
--python version matches the build environment
- Check the application logs for specific error messages
- Contact support if the issue persists
"Activation always fails"
- Verify the license key is correct (copy-paste, check for typos)
- Confirm the license status is
ACTIVE in the Developer Portal
- Check the device limit — the customer may have used all slots
- Ensure the customer has an internet connection for initial activation
"Build is stuck in pending or processing"
- Wait 5-10 minutes; the queue may be under load
- Check the PyLocket status page for service incidents
- If stuck for more than 15 minutes, contact support
"HTTP 402 Payment Required"
- You have exceeded the free tier (10 downloads per app)
- Add a payment method in the Developer Portal → Billing
- Once a subscription is active, the error resolves immediately
Getting Help
If you encounter an error not listed here:
- Check the FAQ for common questions
- Review the Developer Portal for build and license details
- Contact support at support@pylocket.com with:
- Your App ID and Build ID
- The exact error message
- Steps to reproduce