Troubleshooting
Find solutions to common issues when setting up, validating or deploying a SWAT project.
Most issues come from environment differences between your local setup, the CI pipeline
and the target server.
When something fails, always start by identifying where the issue occurs:
locally, in CI, or on the server. Then compare configurations, dependencies and environment variables.
Dependencies not installed
Make sure both backend and frontend dependencies are installed:
composer install
npm install
Assets not built
If styles or scripts are missing, run:
npm run dev or npm run build
Environment misconfiguration
Check your .env files and make sure required variables are defined for your local environment.
Tests failing
Run the same commands locally to reproduce the issue: PHPUnit, PHPStan, ESLint and Vitest.
Missing dependencies
Ensure your composer.json and package.json are up to date and committed before pushing.
Workflow misconfiguration
If you modified the pipeline, make sure all steps, commands and required tools still match your project setup.
SSH connection failed
Verify your GitHub secrets: host, port, user and SSH key.
Make sure your server accepts the connection.
Wrong deployment path
Ensure the deployment directory exists and that the user has the correct permissions.
Environment variables missing
Check that all required variables are configured on the server and not only in your local .env files.
When debugging an issue:
- Check logs first (GitHub Actions, Symfony logs, server logs)
- Try to reproduce the issue locally
- Compare environments (local vs CI vs production)
- Validate each step of the pipeline independently