Troubleshooting
Common issues and solutions for FreeState Terraform backend. This guide covers connectivity problems, authentication issues, state corruption, and performance optimization.
Authentication Issues
401 Unauthorized
Common Causes
- Invalid or expired API key
- Incorrect workspace ID
- API key not properly configured
Solutions
- Check API key configuration in environment variables
- Test API connectivity with curl
- Regenerate API key if needed
State Lock Issues
Locked State
If you encounter a locked state:
- Wait for the operation to complete
- Contact the lock holder if needed
- Use force unlock only if absolutely certain no other operation is running
Performance Issues
Slow Operations
- Optimize state size by splitting large configurations
- Use parallelism limits
- Check network connectivity
Spot Instance Issues
Frequent Service Interruptions
Symptoms
- Service temporarily unavailable errors (503)
- Tasks being stopped with "Spot interruption" reason
- High task replacement frequency
Solutions
- Increase On-Demand capacity percentage in ECS service configuration
- Consider different instance types or availability zones
- Review Spot Instance documentation for optimization strategies
Service Not Recovering After Interruption
Common Causes
- Insufficient ECS service desired count
- Task placement failures due to resource constraints
- Application not handling SIGTERM gracefully
Debugging Steps
- Check ECS service events for placement failures
- Review CloudWatch logs for shutdown behavior
- Verify health check configuration
- Monitor EventBridge for Spot interruption events
Tasks Timing Out During Shutdown
Symptoms
- Tasks killed with SIGKILL after 120 seconds
- Incomplete graceful shutdown logs
- Data loss or corruption warnings
Solutions
- Optimize application shutdown procedures
- Reduce active connection drain time
- Implement proper SIGTERM signal handling
- Review application logs for shutdown bottlenecks
Getting Help
Support Channels
- Email Support: support@freestate.cloud
- Documentation: FreeState Documentation
- Community: Discord and GitHub discussions
When Contacting Support
Include the following information:
- Error messages and stack traces
- Terraform version
- Steps to reproduce the issue
- Workspace information