Troubleshooting

>Common issues and solutions when using SPX Graphics Controller. When production is live, every second counts. Troubleshooting SPX effectively requires a methodical approach by checking the browser console for JavaScript errors, verifying file permissions on your dataroot, and ensuring your [[Documentation/Renderer/Workflows/CasparCG - AMCP|CasparCG]] connections are configured correctly. Most interface "wonkiness" is solved by a simple page refresh (F5), while deeper server issues often stem from invalid JSON in your [[Documentation/Server/Configurations|config.json]]. By understanding common "gotchas" such as missing [[Documentation/Graphic Templates/Overview|template]] definitions or network firewall blocks, you can maintain a stable, high-performance broadcast environment. --- > [!TIP] If you are stuck, [contact us](https://spxgraphics.com/contact) or join our community [SPX Discord](https://bit.ly/joinspx). ## General Issues ## UI Becomes Unresponsive **Symptoms:** Interface freezes, buttons don't respond **Solutions:** - Refresh the page (Ctrl+R or F5) - Check browser console for JavaScript errors - Restart SPX server - Clear browser cache ## Changes Not Saving **Symptoms:** Edits don't persist, items revert **Solutions:** - Refresh the page - Check browser console for errors - Verify write permissions on dataroot folder - Check disk space - Restart SPX server ## Server Won't Start **Symptoms:** Server fails to start, port errors **Solutions:** - Check if port is already in use - Verify [[Documentation/Server/Configurations|config.json]] is valid JSON - Check file permissions - Review error messages in console - Try different port in config ## Template Issues ## Template Definition Missing **Symptoms:** Error: `templateDefinitionMissing` **Solutions:** - Verify [[Documentation/Graphic Templates/Formats/HTML|template]] has `SPXGCTemplateDefinition` in `<head>` - Check template definition is valid JSON - Ensure definition is placed correctly - Re-import template to [[Documentation/Graphics Controller/Project Settings|project]] ## Template Won't Play **Symptoms:** Item doesn't appear, no output **Solutions:** - Check template is added to project - Verify all required fields are filled - Check playout server is configured (for [[Documentation/Renderer/Workflows/CasparCG - AMCP|CasparCG]]) - Review browser console for errors - Test template in browser directly - Check [[Documentation/Renderer/Overview|renderer]] URL is correct ## Template Errors **Symptoms:** JavaScript errors, broken display **Solutions:** - Check browser console for errors - Verify template HTML is valid - Check for missing files (CSS, JS, images) - Test template outside SPX - Review template definition ## CasparCG Issues ## Server Not Found **Symptoms:** Error: "Template requests CasparCG server [SERVERNAME] but a server by that name was not found" **Solutions:** - Verify server name matches exactly (case-sensitive) - Check server is added in [[Documentation/Graphics Controller/Application Configuration|Configuration]] - Ensure server name uses only alphanumeric characters - Restart SPX server after configuration changes ## Connection Failed **Symptoms:** Can't connect to [[Documentation/Renderer/Workflows/CasparCG - AMCP|CasparCG]] **Solutions:** - Verify CasparCG Server is running - Check network connectivity to CasparCG host/port - Check firewall settings - Verify host and port in config - Increase log level to see detailed messages ## Templates Don't Load in CasparCG **Symptoms:** Templates fail to play in CasparCG **Solutions:** - Verify `templatesource` setting in config - Check templates exist in correct location - Verify HTTP access if using HTTP template source - Check template definition is valid - Review CasparCG Server logs ## Network Issues ## Can't Access SPX Remotely **Symptoms:** Can't connect from other machines **Solutions:** - Check firewall allows port 5656 - Verify SPX is bound to correct interface (0.0.0.0, not just localhost) - Check network connectivity - Verify IP address is correct - Test with `http://[ip]:5656` in browser ## Slow Performance **Symptoms:** Laggy interface, slow graphics **Solutions:** - Check network latency - Verify sufficient bandwidth - Reduce template complexity - Check server resources (CPU, RAM) - Consider local SPX instance ## Configuration Issues ## Config File Errors **Symptoms:** Server fails with config errors **Solutions:** - Validate JSON using [JSONLint](https://jsonlint.com/) - Check for syntax errors - Verify all required fields - Review [[Documentation/Server/Configurations|config file]] structure - Restore from backup if needed ## Settings Not Applied **Symptoms:** Changes don't take effect **Solutions:** - **Restart SPX server** after config changes - Verify config file is saved - Check for config file errors - Ensure correct config file is being used ## Browser Issues ## Graphics Don't Appear **Symptoms:** [[Documentation/Renderer/Overview|Renderer]] shows blank or error **Solutions:** - Test renderer URL in browser directly - Check browser console for errors - Verify SPX server is running - Check URL is correct (including port) - Try different browser - Clear browser cache ## Popup Blocked **Symptoms:** Renderer popup doesn't open **Solutions:** - Allow popups for SPX site - Check browser popup blocker settings - Use inline renderer instead of popup - Manually open renderer URL ## Performance Issues ## High CPU Usage **Symptoms:** System becomes slow **Solutions:** - Reduce number of active [[Documentation/Renderer/Layers|layers]] - Optimize template complexity - Check for infinite loops in templates - Monitor system resources - Consider dedicated machine ## Memory Issues **Symptoms:** Out of memory errors **Solutions:** - Check available RAM - Reduce template complexity - Limit number of templates - Restart SPX periodically - Increase system memory ## Logging ## Enable Verbose Logging For troubleshooting, increase log level in [[Documentation/Server/Configurations|config]]: ```json { "general": { "loglevel": "verbose" } } ``` Or for deep analysis: ```json { "general": { "loglevel": "debug" } } ``` > [!info] Set log level back to `info` after troubleshooting, as heavy logging increases disk usage and may affect performance. ## Review Logs Check log files in the logfolder: - `access.log` - Current log file - Older logs may be rotated ## Getting Help ## Knowledge Base Visit the [[Welcome to SPX Docs|SPX Knowledge Base]] for articles on various topics. ## Discord Join the [SPX Discord server](https://bit.ly/joinspx) for community support. ## GitHub Issues Report bugs on [GitHub Issues](https://github.com/TuomoKu/SPX-GC/issues). ## Feedback Form For feature requests and other feedback, use the [Google Forms feedback form](https://forms.gle/T26xMFyNZt9E9S6d8). ## Known Issues ## Gotcha's & Known Issues - If UI becomes wonky, reload the view (F5 / Ctrl+R) - There is spaghetti code whenever worked tired. Try to accept it... - Undocumented features do exist (templateEvents, TTS, pm2, cfg:hostname/usercommapass/greeting...) - This list shouldn't be. At least not here. --- ## Read Next - [[Documentation/Graphics Controller/Application Configuration|Application Configuration]] - Review configuration settings - [[FAQ/Security|Security]] - Security-related troubleshooting - [[Documentation/Server/Configurations|Server Configurations]] - Detailed configuration options - [[Guides/Getting Started/Quick Start|Quick Start]] - Getting started with SPX