Teleporter import fails when custom database paths are configured via FTLCONF environment variables

[vermacodes]

Versions

• Pi-hole: v6.3
• Web: v6.4
• FTL: v6.4.1

Platform

• OS and version: Alpine Linux (Pi-hole Docker image)
• Platform: Docker (docker-compose)

Expected behavior

When exporting a Teleporter backup from a Pi-hole instance with custom database paths (configured via FTLCONF_files_database and FTLCONF_files_gravity environment variables), and then importing that backup into another Pi-hole instance, the adlists and domainlists should be restored successfully.

Actual behavior / bug

Teleporter export includes the gravity and pihole-FTL database files at their custom paths (e.g., /etc/pihole/db/gravity.db), but the import process fails to restore adlists and domainlists because it expects these files at the default paths (/etc/pihole/gravity.db).

The import completes without errors, FTL restarts successfully, but no adlists or domainlists are actually imported. The logs show no processing of gravity database tables (no "Processed adlist" or "Processed domainlist" messages).

Key findings:

1. Export from Pi-hole with custom paths contains: /etc/pihole/db/gravity.db and /etc/pihole/db/pihole-FTL.db
2. Export from Pi-hole with default paths contains: /etc/pihole/gravity.db and /etc/pihole/pihole-FTL.db
3. Import only works when the archive contains files at default paths
4. Pi-hole API works correctly for adding adlists/domains (confirming database and permissions are functional)
5. Same-server import (export and import on same instance) also fails, ruling out any cross-server compatibility issues

Steps to reproduce

1. Create a docker-compose.yml with custom database paths:

environment:
  FTLCONF_files_database: "/etc/pihole/db/pihole-FTL.db"
  FTLCONF_files_gravity: "/etc/pihole/db/gravity.db"
  FTLCONF_files_macvendor: "/etc/pihole/db/macvendor.db"

volumes:
      - "./etc-pihole:/etc/pihole"

2. Ensure that ./etc-pihole on your local computer contains db subdirectory.
3. Start the container: docker-compose up -d
4. Configure some adlists and domainlists via the Web UI
5. Export a Teleporter backup from Settings → Teleporter → Export
6. Extract the ZIP and verify it contains /etc/pihole/db/gravity.db (not /etc/pihole/gravity.db)
7. Import the backup via Settings → Teleporter → Import
8. Observe that adlists and domainlists are not restored
9. Check logs: docker-compose logs pihole | grep -i "adlist\|domainlist\|Processed"
   Result: No "Processed adlist" or "Processed domainlist" messages appear in logs

Logs during import

2025-12-01 23:13:11.817 EST [190/T474] INFO: Ignoring file etc/pihole/pihole.toml in Teleporter archive (not in import list)
2025-12-01 23:13:11.817 EST [190/T474] INFO: Ignoring file etc/pihole/dhcp.leases in Teleporter archive (not in import list)
2025-12-01 23:13:11.817 EST [190/T474] INFO: Restarting FTL: Teleporter (ZIP) import
[... FTL restarts ...]
2025-12-01 23:13:13.249 EST [190/T478] INFO: Compiled 0 allow and 0 deny regex for 0 client in 0.0 msec

Note: No processing of gravity database tables occurs. The import silently skips the database files because they're not at the expected paths.

Additional context

Docker Compose configuration:

# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      # DNS Ports
      - "8553:53/tcp"
      - "8553:53/udp"
      # Default HTTP Port
      - "8080:80/tcp"
      # Default HTTPs Port. FTL will generate a self-signed certificate
      - "8443:443/tcp"
      # Uncomment the below if using Pi-hole as your DHCP Server
      #- "67:67/udp"
      # Uncomment the line below if you are using Pi-hole as your NTP server
      #- "123:123/udp"
    environment:
      # Set the appropriate timezone for your location from
      # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, e.g:
      TZ: "America/NewYork"
      # Set a password to access the web interface. Not setting one will result in a random password being assigned
      FTLCONF_webserver_api_password: "admin"
      FTLCONF_files_database: "/etc/pihole/db/pihole-FTL.db"
      FTLCONF_files_gravity: "/etc/pihole/db/gravity.db"
      FTLCONF_files_macvendor: "/etc/pihole/db/macvendor.db"
      # If using Docker's default `bridge` network setting the dns listening mode should be set to 'ALL'
      FTLCONF_dns_listeningMode: "ALL"
    # Volumes store your data between container upgrades
    volumes:
      # For persisting Pi-hole's databases and common configuration file
      - "./etc-pihole:/etc/pihole"
      # Uncomment the below if you have custom dnsmasq config files that you want to persist. Not needed for most starting fresh with Pi-hole v6. If you're upgrading from v5 you and have used this directory before, you should keep it enabled for the first v6 container start to allow for a complete migration. It can be removed afterwards. Needs environment variable FTLCONF_misc_etc_dnsmasq_d: 'true'
      #- './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      # See https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
      # Required if you are using Pi-hole as your DHCP server, else not needed
      - NET_ADMIN
      # Required if you are using Pi-hole as your NTP client to be able to set the host's system time
      - SYS_TIME
      # Optional, if Pi-hole should get some more processing time
      - SYS_NICE
    restart: unless-stopped

Root cause:
Teleporter export correctly reads the custom database paths from the running configuration and includes files at those paths in the archive. However, Teleporter import appears to have hardcoded expectations for standard paths (/etc/pihole/gravity.db and /etc/pihole/pihole-FTL.db) and doesn't respect the custom paths specified via environment variables.

Comparison:

• With default paths: Export contains etc/pihole/gravity.db - Import works
• With custom paths: Export contains etc/pihole/db/gravity.db - Import silently fails

Workarounds that work:

1. Removing custom path environment variables (using default paths) makes imports work
2. Using Pi-hole API directly to add adlists/domains (confirms database functionality is fine)

Expected fix:
Teleporter import should either:

1. Respect the FTLCONF_files_database and FTLCONF_files_gravity environment variables when determining where to restore database files
2. Automatically detect where database files are located within the archive and restore them to the currently configured paths
3. Show an error/warning if the archive contains files at non-standard paths that cannot be imported
4. Document that custom database paths are incompatible with Teleporter functionality

This issue affects any deployment (Docker, Podman, etc.) that uses custom database paths for better volume organization, which is a common practice for separating config files from database files.

[dschaper]

Wow, thanks for the amazing Issue!

If this really only affects containerized installs and we can be sure that the envvars will always be populated on the instance that is being restored to then I think a simple solution is to use bash variable substitution for the paths.

Something along the lines of RESTORE_PATH=${FTLCONF_files_database:=/etc/pihole/}, which you might be able to patch in to your running setup now while your wait for us to work on a fix to push out.

[yubiuser]

I think this needs to be handled in FTL repo as it manages teleporter im/export.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Please comment or update this issue or it will be closed in 5 days.

[rdwebdesign]

Should we move this issue to FTL or Docker repo?

[DL6ER]

Hi. Thanks for bringing the issue up here. This is the first time I'm seeing it. The issue is indeed that we are expecting at hard-wired paths in the ZIP file. Even though you provided reproduction steps, I am, unfortunately, only traveling with a very limited testing gear right now so I'd very much appreciate if you could verify my attempt at fixing this.

You can build a custom container including my changes following the instructions

git clone https://github.com/pi-hole/docker-pi-hole
cd docker-pi-hole
./build.sh -f fix/custom_gravity_path_teleporter

and then use the generated image (tagged as pihole:local).

[yubiuser]

Should be fixed with the release of #2776 now