Troubleshooting

Use this page as a symptom tree. Each section follows the same pattern:

• Symptom: what you notice.
• Possible causes: the most likely reasons.
• How to confirm: the quickest checks.
• Next step: what to do now.

Setup and Resource Issues

RenamerX opens, but new files never process normally

Symptom: the app opens, but files cannot move through the normal suggestion flow.

Possible causes:

• First-launch resources did not finish downloading.
• The local runtime is incomplete.

How to confirm:

• Reopen onboarding if available and check whether resource download completed.
• Test with one small supported file.

Next step:

• Finish resource setup from Installation.
• If runtime tuning was changed aggressively, compare it with Local AI Runtime.

Video files fail while documents or images still work

Symptom: video items fail, but other supported files still process.

Possible causes:

• Video-processing resources are missing or were not prepared completely.
• The file type is outside the supported video matrix.

How to confirm:

• Try a known-good MP4 file.
• Compare the extension against Supported File Types.

Next step:

• Recheck first-launch resources.
• If only videos fail, keep your testing batch narrow instead of mixing categories.

Rename Quality Issues

Suggestions are too generic or not useful

Symptom: filenames look vague, repetitive, or less specific than expected.

Possible causes:

• The template asks for fields that are hard to extract from that file type.
• Image-detail or runtime settings are too conservative for visual files.
• Controlled terms are too broad.

How to confirm:

• Test the same file with a simpler template.
• Compare results across a smaller, same-type batch.

Next step:

• Reduce the number of required naming fields.
• Review Templates and Naming Fields Dictionary.
• For image-heavy workflows, inspect Local AI Runtime.

Many items in the same batch fail together

Symptom: failure is widespread rather than limited to one or two bad files.

Possible causes:

• Unsupported file types are mixed into the batch.
• The source files contain too little usable text or metadata.
• The template is too ambitious for that file set.

How to confirm:

• Check file extensions against Supported File Types.
• Retry with a simpler template and a smaller subset.

Next step:

• Separate scanned documents from text-rich documents.
• Separate media files from office documents when testing a new template.

The extracted date keeps looking wrong

Symptom: the generated filename includes a date that does not match the date you expected.

Possible causes:

• The file lacks a clear semantic date.
• The only strong signal is metadata or modification time.

How to confirm:

• Compare the file's content date with the filesystem metadata.
• Test a template that does not depend on dcDate.

Next step:

• Use a less date-dependent template.
• If precise day-level accuracy is not realistic, consider a month-level date format.

Apply and Undo Issues

Some files applied successfully, but others failed

Symptom: the batch is partly changed and partly not.

Possible causes:

• RenamerX applies items one by one, not as a single all-or-nothing transaction.
• A subset of files encountered path or apply errors.

How to confirm:

• Filter the workspace by Applied and Failed.
• Review only the failed subset.

Next step:

• Retry failed items only.
• If you need to restore consistency first, undo the successfully applied items, then adjust the template or target conditions and try again.

Clear Batch Workspace did not restore filenames

Symptom: the list is gone, but files stay renamed.

Possible causes:

• Clear deletes Batch workspace records only.

How to confirm:

• Check whether the affected items were already in Applied state before you cleared the workspace.

Next step:

• Use Undo for files that were already written to disk.
• Read Batch Rename for the apply-versus-clear distinction.

Watch Folder Issues

A watch folder exists, but it is not active

Symptom: the configuration card is present, but the folder is not monitoring new files.

Possible causes:

• Monitoring is paused.
• The source path changed or is no longer valid.
• Pro access is not currently active.

How to confirm:

• Check whether the folder shows Active or Paused.
• Confirm the source path still exists.
• Verify current billing state in Credits & License.

Next step:

• Start the watch folder again.
• If Pro access is unavailable, restore a valid license first.

Auto Apply is unavailable or stops being usable

Symptom: Auto Apply cannot be enabled, or a previously expected automation path is no longer valid.

Possible causes:

• The current device is not in an active Pro state.
• License validation downgraded the app back to Free behavior.

How to confirm:

• Check current plan and license state in Preferences.
• Review Credits & License.

Next step:

• Reactivate or revalidate the license if needed.
• Stay in Review First until the billing state is stable again.

Credits and License Issues

I hit the free credit limit

Symptom: new AI work stops and billing-related failures appear on items that still need suggestion generation.

Possible causes:

• The free monthly credit quota has been exhausted.

How to confirm:

• Check remaining credits in Preferences.
• Look for billing-related failures instead of ordinary extraction failures.

Next step:

• Wait for the next monthly credit refresh.
• Use smaller validation batches while testing templates.
• Upgrade if you need steady throughput.

My license key will not activate

Symptom: activation fails even though you believe the key is valid.

Possible causes:

• Extra spaces were included.
• The key is not the correct RenamerX license.
• The key already reached its activation limit.

How to confirm:

• Re-enter the key carefully.
• Confirm you are using the correct purchase record.

Next step:

• Remove whitespace and retry.
• Deactivate another device first if the activation limit is the issue.

Pro features disappeared after a period offline

Symptom: the app behaves like Free again after being offline for a long time.

Possible causes:

• The offline grace window after the last successful validation expired.

How to confirm:

• Check whether the app now reports Free behavior or an expired license state.

Next step:

• Restore network access and validate the license again.
• Review the validation rules in Credits & License.

Preview Issues

The preview panel only shows a generic icon

Symptom: the file still appears in the list, but the preview area is limited.

Possible causes:

• Native preview is unavailable for that file type or platform.

How to confirm:

• Compare with another file type.
• Check whether the file type is supported even if preview is limited.

Next step:

• Continue evaluating the suggestion flow if the file still processes.
• Use Supported File Types to separate preview limitations from true processing limitations.

Good reset strategy

If you do not know where the problem starts:

1. Test one supported file.
2. Test it in Batch Rename.
3. Use a simple template with three or four fields.
4. Review the suggestion before you apply.

That isolates most issues quickly.