Common Errors

License Issues

License Activation Fails

If you see an error when trying to activate your license key, check the following:

• Verify the cryptography library is installed. Run pip install cryptography if needed.
• Ensure you are copying the entire license key including any dots. The key format is data.signature with exactly one dot separating the two parts.
• Check that no extra whitespace or line breaks were included when pasting.
• Verify the license key file is writable at the expected location (see File Formats & Locations).

"Feature Requires Studio Tier"

This message appears when attempting to use a cloud feature (remote training, live streaming, advanced models) with a Free tier license. Cloud features require a Studio license.

• Check your current tier in the status bar (bottom-right of the window).
• Click the "Upgrade" link or go to Help > Activate License to enter a Studio key.
• All local processing features are available on the Free tier.

Lost License Key

If you have lost your license key:

1. Check your email inbox (and spam folder) for the original license delivery from Recaster.
2. Log into the Customer Portal to view your license key.
3. Use the "Resend License" feature on the portal license page to receive a fresh copy by email.

License Validation Fails After Update

If your license stops working after updating Recaster, the license file may have been corrupted during the update process. Try re-activating with your original license key. If that does not work, contact support on Discord.

Content Blocked

Challenge-25 Policy

Recaster uses a Challenge-25 policy to prevent processing of content that may involve minors. If a detected face appears to be under 25 years old, processing will be blocked. This is a legal safety measure and cannot be bypassed.

If you encounter a false positive where an adult face is being blocked:

• Try using a different source or target image with clearer adult features.
• Ensure the face is well-lit and clearly visible in the image.
• The FairFace classifier uses age ranges (not exact ages), so some margin of error exists.

Video Safety Scan Taking Too Long

Before processing a video, Recaster scans frames at regular intervals to check for minor-appearing faces. Longer videos take longer to pre-scan. Processing begins only after the safety scan completes successfully.

Model Download Errors

SwinIR Download Fails (HTTP 401)

SwinIR models are hosted on Hugging Face repositories that require authentication. If you see an HTTP 401 Unauthorized error when downloading SwinIR, you need to add a Hugging Face token to your settings.

1. Get a Hugging Face access token from huggingface.co/settings/tokens.
2. Open your settings file (see File Formats & Locations).
3. Add the field "hf_token": "hf_YOUR_TOKEN_HERE" to the JSON object.
4. Restart Recaster and retry the download.

BIPA Consent Issues

Consent Dialog Keeps Appearing

The BIPA consent dialog should only appear on first launch (or after a consent version change). If it keeps appearing:

• Check your settings file for bipa_consent.consent_given: true.
• Verify the consent_version matches the current version (1.0).
• Ensure the settings file is writable (not read-only or locked).

Application Exits Immediately on Startup

If you declined the BIPA consent dialog, the application will exit. This is by design since consent is required for face processing. To reset:

1. Delete the settings file to reset all preferences.
2. Restart Recaster. The consent dialog will appear again.
3. Accept the consent to proceed.

"Facial Data Processing Requires Explicit Consent"

This error comes from a defense-in-depth consent check in the processing pipeline. It means consent verification was triggered but found no valid consent. Restart the application and accept the consent dialog to resolve.

Application Crashes

Crash on Startup

If Recaster crashes when launching, try the following steps in order:

1. Clear settings: Delete or rename the settings folder for your platform (see File Formats & Locations), then restart.
2. Update GPU drivers: Outdated or corrupted drivers frequently cause startup crashes.
3. Reinstall Recaster: Download the latest version and install fresh.
4. Check system requirements: Verify your hardware meets the minimum specs in GPU Requirements.

Crash During Processing

Crashes during face swapping, enhancement, or upscaling are typically caused by insufficient GPU memory (VRAM). Try:

• Closing other GPU-intensive applications (games, video editors, other AI tools).
• Reducing the tile size in upscaling settings (256 or 128 instead of 512).
• Using a smaller model variant (e.g. InSwapper 128-FP16 instead of Ghost 3).
• Processing lower-resolution input files.

Remote Processing Issues

SSH Connection Fails

If you cannot connect to a remote instance:

• Verify key permissions: chmod 600 on the SSH key file.
• Check that the remote instance is running in the Remote panel.
• Test the connection manually from your terminal.
• Ensure your firewall is not blocking outbound SSH connections.

Remote Preview Not Updating

If the live preview or Quick Recast preview is not updating during remote processing:

• Verify the remote instance is actively processing (check the progress indicator).
• Check the preview interval setting (default: 5 seconds).
• Ensure the SSH connection is stable (no network interruptions).
• Try stopping and restarting the processing task.