Skip to content

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
Build failed: MALWARE_DETECTED VirusTotal flagged the artifact Review your artifact for false positives. If legitimate, contact support.
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 not registered for this app Add the platform: pylocket apps update --app <ID> --platform <PLATFORM>
Build status: FAILED Generic build failure Check the build details for a specific error message

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 _pylocket_rt file 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 grace period exceeded 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"

  1. Verify all three files are present: executable, _pylocket_rt, .pylocket_manifest
  2. Check that the --python version matches the build environment
  3. Check the application logs for specific error messages
  4. Contact support if the issue persists

"Activation always fails"

  1. Verify the license key is correct (copy-paste, check for typos)
  2. Confirm the license status is ACTIVE in the Developer Portal
  3. Check the device limit — the customer may have used all slots
  4. Ensure the customer has an internet connection for initial activation

"Build is stuck in QUEUED"

  1. Wait 5-10 minutes — the queue may be under load
  2. Check the PyLocket status page for service incidents
  3. If stuck for more than 15 minutes, contact support

"HTTP 402 Payment Required"

  1. You have exceeded the free tier (10 downloads per app)
  2. Add a payment method in the Developer Portal → Billing
  3. Once a subscription is active, the error resolves immediately

Getting Help

If you encounter an error not listed here:

  1. Check the FAQ for common questions
  2. Review the Developer Portal for build and license details
  3. Contact support at support@pylocket.com with:
  4. Your App ID and Build ID
  5. The exact error message
  6. Steps to reproduce