Troubleshooting

Here are solutions to some common issues encountered with Recommendarr.

Cookie Errors with Reverse Proxy

Symptom: When using Recommendarr behind an HTTPS reverse proxy, you might encounter errors in the browser console or server logs related to cookies, such as:

Cookie "session" has been rejected because a non-HTTPS cookie can't be set as "secure".

or similar messages about auth_token.

Cause: This typically happens when your reverse proxy terminates the HTTPS connection (handling the SSL certificate) and forwards the request to the Recommendarr container via plain HTTP. The application, seeing an HTTP connection, doesn't set the Secure flag on its session cookies, but the browser (connected via HTTPS) rejects non-secure cookies.

Solution:

1. Set FORCE_SECURE_COOKIES=true: Add this environment variable to your Recommendarr configuration (Docker run command, docker-compose.yml, or .env file). This tells the application to always set the Secure flag on cookies, even if the direct connection from the proxy is HTTP.

# Example in docker-compose.yml
environment:
  - FORCE_SECURE_COOKIES=true
  # ... other variables

2. Ensure X-Forwarded-Proto Header: Verify that your reverse proxy is correctly sending the X-Forwarded-Proto header, set to https. This header informs the application that the original client connection was secure.

• Nginx: Add proxy_set_header X-Forwarded-Proto $scheme; to your location block.
• Traefik: Usually handles this automatically, but ensure it's configured correctly if issues persist.
• Other Proxies: Consult your proxy's documentation for forwarding the protocol scheme.

3. Restart Recommendarr: Apply the changes by restarting the application container or process.

See Reverse Proxy Setup for more details and configuration examples.

Incorrect Port Mapping

Symptom: Unable to access Recommendarr in the browser, connection refused errors.

Cause: Mismatch between the port Recommendarr is configured to run on (PORT environment variable, default 3000) and the port exposed/mapped in Docker or accessed directly.

Solution:

• Ensure the PORT environment variable matches the internal port number used in your Docker port mapping (e.g., -p 8080:3000 means PORT should be 3000, and you access via 8080).
• It's generally recommended to keep internal and external ports the same unless you have a specific reason not to (e.g., -p 3000:3000 and PORT=3000).
• If changing the port, update both the PORT environment variable and the Docker port mapping (-p or ports: section).
• Verify no other service is using the host port you are trying to map.

Development Setup Issues

If you are running the application manually for development (npm run dev, npm run serve, npm run api):

• Frontend Port: The development frontend server (npm run serve) runs on port 8080 by default and includes hot reloading.
• API Port: The development backend server (npm run api) runs on port 3050 by default.
• Unified Port: The production/unified server (npm run unified or Docker) runs both frontend and backend on a single port defined by the PORT environment variable (default 3000).
• Ensure you are accessing the correct port for the mode you are running.
• Check the terminal output for any build errors (npm install, npm run build) or runtime errors when starting the servers.

Other Issues

• Check Logs: Examine the Recommendarr server logs (Docker logs or terminal output) for specific error messages.
• Service Connectivity: Ensure Recommendarr can reach your Sonarr, Radarr, Plex, etc., instances at the URLs provided. Firewalls or network configurations might block connections. Using host.docker.internal might be necessary in Docker Compose if services are on the host machine.
• API Keys: Double-check that the API keys entered for Sonarr, Radarr, AI services, etc., are correct and have the necessary permissions.