gitea_ui/docs/troubleshooting.md

Troubleshooting Guide

This guide provides solutions to common issues you might encounter when using the Hostbasket application.

Table of Contents

1. Authentication Issues
   • Missing CSRF Token
   • Invalid CSRF Token
   • JWT Token Issues
2. OAuth Issues
   • Gitea Authentication Errors
3. Server Issues
   • Port Already in Use
   • Template Parsing Errors

Authentication Issues

Missing CSRF Token

Problem: When trying to authenticate with Gitea, you receive a "Missing CSRF token" error.

Solutions:

1. Check your SECRET_KEY environment variable:

   • Ensure you have a valid SECRET_KEY in your .env file
   • The SECRET_KEY must be at least 32 bytes long
   • Example: SECRET_KEY=01234567890123456789012345678901

2. Enable debug logging:

   • Set RUST_LOG=debug in your .env file
   • Restart the application
   • Check the logs for more detailed information

3. Clear browser cookies:

   • Clear all cookies for your application domain
   • Try the authentication process again

4. Check session configuration:

   • Make sure your session middleware is properly configured
   • The SameSite policy should be set to "Lax" for OAuth redirects

Invalid CSRF Token

Problem: When trying to authenticate with Gitea, you receive an "Invalid CSRF token" error.

Solutions:

1. Check for multiple tabs/windows:

   • Make sure you're not trying to authenticate in multiple tabs/windows simultaneously
   • Each authentication attempt generates a new CSRF token

2. Check for browser extensions:

   • Some browser extensions might interfere with cookies or redirects
   • Try disabling extensions or using a different browser

JWT Token Issues

Problem: You're logged in but keep getting redirected to the login page.

Solutions:

1. Check JWT_SECRET:

   • Ensure your JWT_SECRET is consistent across application restarts
   • Set a permanent JWT_SECRET in your .env file

2. Check token expiration:

   • The default token expiration is 24 hours
   • You can adjust this with the JWT_EXPIRATION_HOURS environment variable

OAuth Issues

Gitea Authentication Errors

Problem: You encounter errors when trying to authenticate with Gitea.

Solutions:

1. Check OAuth configuration:

   • Verify your GITEA_CLIENT_ID and GITEA_CLIENT_SECRET are correct
   • Make sure your GITEA_INSTANCE_URL is correct and accessible
   • Ensure your APP_URL is set correctly for the callback URL

2. Check Gitea application settings:

   • Verify the redirect URI in your Gitea application settings matches your callback URL
   • The redirect URI should be: http://localhost:9999/auth/gitea/callback (adjust as needed)

3. Check network connectivity:

   • Ensure your application can reach the Gitea instance
   • Check for any firewalls or network restrictions

Server Issues

Port Already in Use

Problem: When starting the application, you get an "Address already in use" error.

Solutions:

1. Change the port:

   • Set a different port in your .env file: APP__SERVER__PORT=8080
   • Or use the command-line flag: cargo run -- --port 8080

2. Find and stop the process using the port:

   • On Linux/macOS: lsof -i :9999 to find the process
   • Then kill <PID> to stop it

Template Parsing Errors

Problem: The application fails to start with template parsing errors.

Solutions:

1. Check template syntax:

   • Verify that all your Tera templates have valid syntax
   • Look for unclosed tags, missing blocks, or invalid expressions

2. Check template directory:

   • Make sure your APP__TEMPLATES__DIR environment variable is set correctly
   • The default is ./src/views