Troubleshooting
Solutions to common issues you might encounter when using DBCraft.
Container won't start
Symptoms
- Container exits immediately
- Port already in use
- Permission denied errors
Solutions
- Check if port 3001 (or your configured port) is available
- Verify the data volume has correct permissions
- Run `docker logs dbcraft` to see error messages
- Ensure Docker has enough memory allocated (minimum 256MB)
Can't connect to database
Symptoms
- Connection timeout
- Authentication failed
- SSL errors
Solutions
- Verify database host is accessible from DBCraft container
- Check credentials are correct (username, password)
- Ensure the database is accepting connections from DBCraft's IP
- For Docker, use `host.docker.internal` instead of `localhost`
- Enable SSL if your database requires it
Query execution fails
Symptoms
- Query timeout
- Permission denied
- Syntax errors
Solutions
- Check the database user has SELECT permissions
- Verify the query syntax is correct for your database type
- For large queries, increase the timeout in data source settings
- Check for special characters that may need escaping
Dashboard not loading
Symptoms
- Blank dashboard
- Charts show errors
- Slow loading
Solutions
- Clear browser cache and reload
- Check browser console for JavaScript errors
- Verify all data sources are connected
- Ensure queries in charts are still valid
Still Need Help?
If you can't find a solution, reach out to our community.