CosmosCost LogoCosmosCost

Troubleshooting

Common issues and solutions to help you resolve problems with CosmosCost.

Quick Diagnostics

Before diving into specific issues, try these quick diagnostic steps:

Health Check

Visit /api/health to check if the API is responding.

Authentication Issues

Cannot Log In

Symptoms: Login page shows errors, credentials rejected

Solutions:

  1. Verify you're using the correct environment mode (local vs production)
  2. In local development, any password works for test users
  3. Check browser console for JavaScript errors
  4. Clear browser cookies and cache
  5. Try GitHub OAuth as an alternative (production only)

Session Expires Quickly

Symptoms: Logged out frequently, need to re-authenticate

Solutions:

  1. Check NEXTAUTH_SECRET is properly configured
  2. Verify environment variables are loaded correctly
  3. Check browser settings for cookie restrictions
  4. Ensure system clock is accurate

OAuth Not Working

Symptoms: GitHub login button missing or not working

Solutions:

  1. OAuth is only available in production mode
  2. Set NEXT_PUBLIC_USE_LOCAL_AUTH=false for production
  3. Verify GitHub OAuth app configuration
  4. Check redirect URLs in GitHub app settings

Customer Access Issues

Access Denied to Customer

Symptoms: Error message about customer access

Solutions:

  1. Verify you're a member of the customer organization
  2. Check the customer slug in the URL is correct
  3. Contact the customer admin to verify your membership
  4. Ensure you have the appropriate role (admin/member)

Cannot Create Organization

Symptoms: Onboarding fails, organization creation errors

Solutions:

  1. Check database connection is working
  2. Verify user is properly authenticated
  3. Ensure organization name doesn't already exist
  4. Check browser console for JavaScript errors

API Issues

401 Unauthorized Errors

Symptoms: API calls return 401 status

Solutions:

  1. Verify JWT token is included in Authorization header
  2. Check token format: Bearer YOUR_TOKEN
  3. Ensure token hasn't expired
  4. Try refreshing your authentication token

403 Forbidden Errors

Symptoms: API calls return 403 status

Solutions:

  1. Verify you have access to the customer organization
  2. Check your role has sufficient permissions
  3. Ensure customer_id parameter is correct
  4. Contact customer admin to verify your access level

Rate Limiting (429 Errors)

Symptoms: API calls return 429 status

Solutions:

  1. Wait for the rate limit window to reset
  2. Implement exponential backoff in your code
  3. Reduce the frequency of API calls
  4. Consider caching responses where appropriate

Cloud Account Issues

Cannot Connect Cloud Account

Symptoms: Cloud account connection fails

Solutions:

  1. Verify cloud provider credentials are correct
  2. Check IAM permissions in your cloud account
  3. Ensure Cost and Usage Reports are enabled (AWS)
  4. Contact support for credential storage issues

Data Sync Failures

Symptoms: Cost data not updating, sync errors

Solutions:

  1. Check cloud account status in dashboard
  2. Verify billing export configurations
  3. Ensure data is available in cloud provider
  4. Contact support if issues persist

Subscription & Billing Issues

Plan Features Not Working

Symptoms: Premium features show upgrade prompts

Solutions:

  1. Verify your subscription status is active
  2. Check trial period hasn't expired
  3. Refresh your browser session
  4. Contact billing support for payment issues

Payment Processing Errors

Symptoms: Credit card declined, payment failures

Solutions:

  1. Verify card details are correct
  2. Check card has sufficient funds
  3. Contact your bank about international payments
  4. Try a different payment method

Development Issues

Docker Services Won't Start

Symptoms: Docker containers fail to start

Solutions:

  1. Ensure Docker is running on your system
  2. Check port 5432 (PostgreSQL) isn't in use
  3. Run docker system prune -f to clean up
  4. Restart Docker service
  5. Check Docker logs for specific errors

Database Migration Errors

Symptoms: Migration commands fail

Solutions:

  1. Ensure PostgreSQL container is running
  2. Check database connection settings
  3. Run npm run db:reset to start fresh
  4. Verify SQL files exist in migrations directory

Build or Start Errors

Symptoms: npm run dev or build fails

Solutions:

  1. Delete node_modules and run npm install
  2. Clear Next.js cache: rm -rf .next
  3. Check Node.js version (requires 18+)
  4. Verify environment variables are set
  5. Check for TypeScript compilation errors

Theme and UI Issues

Theme Not Changing

Symptoms: Theme toggle doesn't work

Solutions:

  1. Check browser localStorage for theme preference
  2. Refresh the page after theme change
  3. Clear browser cache and cookies
  4. Verify JavaScript is enabled

UI Components Not Loading

Symptoms: Missing styles, broken layout

Solutions:

  1. Check browser console for CSS/JavaScript errors
  2. Verify Tailwind CSS is compiled properly
  3. Clear browser cache
  4. Check for conflicting browser extensions

Getting Additional Help

Debug Information to Collect

When reporting issues, please include:

  • •Steps to reproduce the problem
  • •Expected vs actual behavior
  • •Browser and operating system information
  • •Screenshots or error messages
  • •Browser console logs (F12 → Console)
  • •Network requests (F12 → Network tab)

Support Channels

  1. Documentation: Search this documentation first
  2. FAQ: Check the frequently asked questions
  3. Community: Join our Discord community
  4. Support: Contact us through the support page

Emergency Issues

For critical production issues:

  • •Business+ customers: Contact your dedicated account manager
  • •Business customers: Use priority support channel
  • •Free users: Use community support for non-critical issues

Still Need Help?

Don't see your issue here? Contact our support team - we're here to help!

This troubleshooting guide is regularly updated. If you find a solution to an issue not listed here, please let us know so we can help other users.