FAQ

Sometimes, you might encounter unexpected errors. Before reporting an issue, please try the following steps:

Fresh Install

If you're experiencing strange issues, a fresh install can often resolve them. This involves removing existing data and caches.

• remove all folders (what you have defined in your compose or depending on your setup)
• rerun Configarr which recreates cache folders and more

Custom TRaSH-Guide or Recyclarr Template URLs

If you have configured a custom trashGuideUrl or recyclarrUrl, caching issues might occur. In this case, clearing the cache folders is recommended.

• remove the folders for the caches
• rerun Configarr

Error: "Recv failure: Connection reset by peer"

If you see an error like:

GitResponseError: unable to access 'https://github.com/recyclarr/config-templates/': Recv failure: Connection reset by peer

This can be caused by Docker bridge network issues, especially with DNS, TLS, or MTU settings. The problem may only occur when using Docker's default bridge network, and not with network_mode: host.

Reference issues:

• https://github.com/raydak-labs/configarr/issues/300 (thanks for @jtnqr for helping trouble shooting)

Troubleshooting Steps

• Try running Configarr with network_mode: host in your Docker Compose file. This often resolves the issue immediately.

• Check your DNS and MTU settings if you use custom networking (VPN, Pi-hole, etc.).

• If you have a VPN or custom DNS setup, try disabling them temporarily to see if the problem persists.

• You can also manually clone the repo inside the container to verify if plain git works:

  docker exec -it <container_name> sh
  git clone https://github.com/recyclarr/config-templates/
  # also check git pull

Example Docker Compose workaround

services:
	configarr:
		network_mode: host
		# ...other options

Note: Using network_mode: host is generally safe for Configarr, as it does not expose ports by default. However, be aware of your environment's security requirements.

DNS Resolution Problems (Could not resolve host: github.com)

If you encounter errors like:

GitError: Cloning into '/app/repos/trash-guides'...
fatal: unable to access 'https://github.com/TRaSH-Guides/Guides/': Could not resolve host: github.com

This is usually caused by DNS issues inside the Docker container. Even if DNS works on your host and inside the container when tested manually, the error may still occur intermittently for git operations.

Troubleshooting Steps

• Test DNS resolution inside the container:

  docker run --rm -it busybox nslookup github.com

• Try changing your DNS server to a public DNS (e.g., 1.1.1.1 or 8.8.8.8) on your host or in your Docker configuration.
• Avoid using ISP DNS servers, as they may cause intermittent failures.
• Restart the container after changing DNS settings.
• If you use custom Docker networks, test with the default bridge or host network.

Reference issues:

• https://github.com/raydak-labs/configarr/issues/266
• https://github.com/raydak-labs/configarr/issues/188

Git Clone Errors with Legacy Kernels

If you encounter errors like:

Error: Unable to checkout revision 'master' from 'https://github.com/recyclarr/config-templates'. The revision may not exist in the repository. Error: index-pack failed

or

Function not implemented

This can be caused by legacy kernels that don't support modern git clone options like --filter=blob:none or sparse checkout features.

Solution

Set the CONFIGARR_DISABLE_GIT_CLONE_OPTIONS environment variable to disable these advanced git clone options:

Docker Compose:

services:
  configarr:
    environment:
      - CONFIGARR_DISABLE_GIT_CLONE_OPTIONS=1
    # ...other options

Docker run:

docker run -e CONFIGARR_DISABLE_GIT_CLONE_OPTIONS=1 ...

Kubernetes:

env:
  - name: CONFIGARR_DISABLE_GIT_CLONE_OPTIONS
    value: "1"

When this variable is set, Configarr will perform standard git clones without the --filter=blob:none or --sparse options, which should work with older kernel versions.

Reference issues:

• https://github.com/raydak-labs/configarr/issues/367

TRaSH-Guides Breaking Changes (Feb 2026)

Breaking Change

TRaSH-Guides made significant changes to their JSON structure in February 2026. This affects both CF group semantics and quality profile ordering.

Commit: 2994a7979d8036a7908a92e2cd286054fd4fcc1b

What Changed

1. CF Groups: exclude → include semantics

// OLD: CFs applied to ALL profiles EXCEPT listed ones
"quality_profiles": {
  "exclude": { "HD Bluray + WEB": "..." }
}

// NEW: CFs applied ONLY to listed profiles
"quality_profiles": {
  "include": { "Remux + WEB 1080p": "..." }
}

2. Quality Profile Items: API order → Display order

• Before: Quality items in API response order (internal)
• After: Quality items in display order (highest-to-lowest priority)

Backward Compatibility

Option 1: Pin to TRaSH-Guides revision (recommended for stability)

For Configarr versions < 1.22.0, pin to the last commit before the changes:

# config.yml
trashRevision: d2105f2e1b04c7e30ae44e73d682298609438216

This uses the old TRaSH-Guides structure without needing the compatibility flag.

Option 2: Use compatibility flag (Configarr >= 1.22.0)

For Configarr versions >= 1.22.0, use the new TRaSH-Guides structure with the compatibility flag if needed:

# config.yml
# Enable for old TRaSH-Guides behavior (before Feb 2026)
compatibilityTrashGuide20260219Enabled: true

Setting	CF Groups	Quality Ordering
false (default)	include semantics	Display order (no reversal)
true	exclude semantics	API order (with reversal)

Temporary Flag

The compatibilityTrashGuide20260219Enabled flag is temporary and will be removed in a future version. It's recommended to update to the latest TRaSH-Guides version.

Version Matrix

Configarr Version	TRaSH-Guides Default	Old Behavior Via
< 1.22.0	Old structure	N/A (default)
>= 1.22.0	New structure	compatibilityTrashGuide20260219Enabled: true OR trashRevision: d2105f2e1b04c7e30ae44e73d682298609438216