littleshop/TROUBLESHOOTING.md

LittleShop Troubleshooting Guide

Common Issues and Solutions

🔴 HTTP 500 Error on Login

Symptoms

• Login page loads (HTTP 200)
• Submitting credentials returns HTTP 500
• Error: "Request reached the end of the middleware pipeline"

Root Causes & Fixes

1. JWT Key Configuration Issue

Problem: JWT key environment variable name mismatch or key too short

Error Message:

IDX10720: Unable to create KeyedHashAlgorithm for algorithm 'http://www.w3.org/2001/04/xmldsig-more#hmac-sha256',
the key size must be greater than: '256' bits, key has '136' bits.

Solution:

# CORRECT - Use Jwt__Key (double underscore)
-e Jwt__Key="ThisIsAVeryLongSecretKeyThatIsDefinitelyLongerThan32BytesForSure123456789ABCDEF"

# WRONG - These won't work
-e JWT_SECRET_KEY="..."  # Wrong variable name
-e Jwt_Key="..."          # Single underscore
-e Jwt__Key="shortkey"    # Key too short (< 32 bytes)

2. Parameter Case Sensitivity

Problem: Form sends lowercase but method expected uppercase

Solution: Already fixed in code - Login method now accepts both cases:

public async Task<IActionResult> Login(string Username, string Password)
{
    var username = Username?.ToLowerInvariant();
    var password = Password;
    // ...
}

3. Port Configuration Issue

Problem: App listening on wrong port

Solution:

# CORRECT
-e ASPNETCORE_URLS="http://+:8080"

# WRONG
-e ASPNETCORE_HTTP_PORTS=8080  # This doesn't work

---

🔴 Container Shows "Unhealthy"

Symptoms

• Container running but marked as unhealthy
• Health check failing

Solution

1. The health check includes database check which can timeout during initialization
2. App still works even if marked unhealthy
3. To disable health check issues, run without health check or increase timeout

---

🔴 Database Permission Errors

Symptoms

• SQLite Error 8: attempt to write a readonly database
• Cannot create or update database

Solution

# Database MUST be owned by UID 1654
sudo chown -R 1654:1654 /opt/littleshop/data/

---

🔴 Network Connectivity Issues

Symptoms

• Containers can't communicate
• SilverPay API unreachable
• "Name or service not known" errors

Solution

# All containers must be on littleshop-network
docker network connect littleshop-network littleshop-admin
docker network connect littleshop-network silverpay-api
docker network connect littleshop-network nginx-proxy-manager

---

🔴 Anti-forgery Token Validation Errors

Symptoms

• 400 Bad Request on form submissions
• CSRF token validation failures

Current Status

• Anti-forgery validation is temporarily disabled on login
• This is noted in the code: // [ValidateAntiForgeryToken] // Temporarily disabled for HTTPS proxy issue

---

Quick Diagnostics

Check Container Status

docker ps --format "table {{.Names}}\t{{.Status}}" | grep littleshop

Check Logs for Errors

docker logs littleshop-admin --tail 50 | grep -E "Exception|ERROR|fail"

Test Login Locally

docker exec littleshop-admin curl -X POST http://localhost:8080/Admin/Account/Login \
  -d "Username=admin&Password=admin" \
  -o /dev/null -w "Status: %{http_code}\n"

Check Environment Variables

docker exec littleshop-admin printenv | grep -E "Jwt|ASPNETCORE"

---

Recovery Procedures

Complete Reset

# Stop everything
docker stop littleshop-admin
docker rm littleshop-admin

# Clean up
sudo rm -rf /opt/littleshop/data/*

# Fix permissions
sudo mkdir -p /opt/littleshop/{data,logs,uploads}
sudo chown -R 1654:1654 /opt/littleshop/data/

# Redeploy
./deploy-littleshop.sh

Emergency Development Mode

To see detailed errors:

docker run -d \
  --name littleshop-admin \
  --network littleshop-network \
  -p 127.0.0.1:5100:8080 \
  -v /opt/littleshop/data:/app/data \
  -e ASPNETCORE_ENVIRONMENT=Development \
  -e ASPNETCORE_URLS="http://+:8080" \
  -e ConnectionStrings__DefaultConnection="Data Source=/app/data/littleshop-production.db" \
  -e Jwt__Key="ThisIsAVeryLongSecretKeyThatIsDefinitelyLongerThan32BytesForSure123456789ABCDEF" \
  littleshop:latest

---

Critical Configuration Points

Must-Have Environment Variables

ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:8080  # NOT HTTP_PORTS!
Jwt__Key=[minimum 32 bytes]    # Double underscore!
ConnectionStrings__DefaultConnection=Data Source=/app/data/littleshop-production.db

Required Docker Network

littleshop-network (external)

Required Permissions

/opt/littleshop/data: UID 1654
/opt/littleshop/logs: UID 1654
/opt/littleshop/uploads: UID 1654