# Troubleshooting Guide

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

## Table of Contents

1. [Authentication Issues](#authentication-issues)
   - [Missing CSRF Token](#missing-csrf-token)
   - [Invalid CSRF Token](#invalid-csrf-token)
   - [JWT Token Issues](#jwt-token-issues)
2. [OAuth Issues](#oauth-issues)
   - [Gitea Authentication Errors](#gitea-authentication-errors)
3. [Server Issues](#server-issues)
   - [Port Already in Use](#port-already-in-use)
   - [Template Parsing Errors](#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`