Vroum Docs

Appearance

Troubleshooting Guide ​

Common Issues & Resolutions ​

1. PostgreSQL Connection Errors ​

Error:

SQLSTATE[08006] [7] could not translate host name \"pgsql\" to address

Cause: Docker (Sail) containers not running. Fix:

bash
./vendor/bin/sail up -d

Re-run migrations/tests afterward.

2. Frontend Assets Not Updating ​

Symptoms: Stale JS/CSS, missing components. Fix:

bash
npm run build
# or restart dev server
npm run dev

Ensure Vite server is running in dev.

3. TypeScript Types Missing / Outdated ​

Cause: Data/Enum changes not transformed yet. Fix:

bash
composer run transform-types

Confirm resources/js/types/generated.ts and resources/js/types/enumRegistry.ts regenerated. A [hydrateEnums] Unknown enum "…" console warning is the same problem seen from the browser: the enum registry is stale.

Also check the class carries the #[TypeScript] attribute — untagged Data classes are silently skipped.

4. Pint Style Violations ​

Fix all automatically:

bash
./vendor/bin/sail pint --dirty

Test only:

bash
./vendor/bin/sail pint --test

If persistent, verify the file includes declare(strict_types=1);. tests/TestCase.php is excluded from Pint by design.

5. ESLint Import Errors (Missing Extension) ​

import-x/extensions is set to always (with ignorePackages: true). Fix: add the explicit extension to relative and aliased imports:

ts
import useFeature from './useFeature.ts';
import { modalPlugin } from '@/Plugins/modal.ts';

Bare package specifiers (import { ref } from 'vue') stay as-is.

6. Queue Jobs Not Executing ​

Horizon runs in its own container. Check it is up and follow its output:

bash
./vendor/bin/sail up -d
docker compose logs -f horizon
docker compose restart horizon

If the watcher stops restarting Horizon after an edit, make sure Docker Desktop is using VirtioFS (Settings → General → file sharing implementation) so file-system events reach the container.

7. WebSocket Events Not Received ​

  • Verify Reverb server configuration (config/reverb.php).
  • Confirm frontend Echo instance uses correct host/port.
  • Check channel authorization callbacks in routes/channels.php.

8. Sentry Events Missing ​

  • Confirm SENTRY_DSN is set in .env.
  • Verify initialization code in Vue entry file.
  • Check sampling rates in config/sentry.php.

9. Media File Access Errors ​

  • Ensure storage disk configured (FILESYSTEM_DISK=...).
  • Run ./vendor/bin/sail artisan storage:link if the symbolic link is missing.
  • Locally, object storage is MinIO — check that container and the AWS_* variables.

10. PDF Generation Failures ​

  • Browsershot renders against the chromium container — confirm it is running and that config/browser-shot.php points at it.
  • Ensure necessary fonts are installed if the layout is broken.

10b. Search Returns Nothing ​

  • Confirm the meilisearch container is up.
  • Push index settings and reindex:
bash
./vendor/bin/sail artisan scout:sync-index-settings
./vendor/bin/sail artisan scout:import "App\Models\Car"
  • Missing results for one tenant usually means shop_id is absent from toSearchableArray().
  • In tests search is a no-op on purpose (SCOUT_DRIVER=null).

11. Permission Denied Errors ​

  • Clear permission cache after role/permission changes:
bash
./vendor/bin/sail artisan permission:cache-reset

12. Deep Relationship Query Performance ​

  • Use selective eager loading; limit nested depth.
  • Consider caching results when stable.

13. Webhook Signature Failures ​

  • Validate signing secret in .env matches provider.
  • Confirm profile configuration in config/webhook-client.php.

14. Test Flakiness (Timing / Async) ​

  • Avoid relying on queued jobs finishing; dispatch synchronously or mock.
  • Use Bus::fake() / Event::fake() to assert dispatch.

15. Missing Generated Icons ​

Run generation script:

bash
npm run generate:icons

16. Tests Fail With a Vite Manifest Error ​

The test class is extending Laravel's base TestCase instead of Tests\TestCase / Tests\DatabaseTestCase, which mock Illuminate\Foundation\Vite. CI never builds assets, so this fails there even when it passes locally.

17. Unexpected Redirect Instead of 403 ​

EnsureUserTypeShop / EnsureUserTypeClient redirect (302) on a wrong user type. A 403 comes from a policy or an Action's authorize(). Assert the one that actually applies.

18. Tenant Data Leaking or Missing in a Job ​

Never serialize a Shop into a queued job. Resolve it inside the job with Shop::current().

Diagnostic Commands ​

TaskCommand
Laravel version./vendor/bin/sail artisan --version
App overview./vendor/bin/sail artisan about
Horizon status./vendor/bin/sail artisan horizon:status
Queue size./vendor/bin/sail artisan horizon:workload
Cache clear./vendor/bin/sail artisan cache:clear
Config clear./vendor/bin/sail artisan config:clear
Route list./vendor/bin/sail artisan route:list
Slowest tests./vendor/bin/sail artisan test --profile

Logging & Monitoring ​

  • Stream logs with ./vendor/bin/sail artisan pail.
  • Sentry dashboard for exception traces.
  • Pulse (/pulse) for slow queries, slow jobs, 4xx responses and dependency health.
  • Activity Log for domain event auditing.

When All Else Fails ​

  1. Rebuild containers: ./vendor/bin/sail down && ./vendor/bin/sail up -d.
  2. Clear caches: ./vendor/bin/sail artisan optimize:clear.
  3. Reinstall node modules: rm -rf node_modules && npm install.
  4. Re-run migrations on a fresh DB: ./vendor/bin/sail artisan migrate:fresh --seed (destructive — local only).

See security.md for secure configuration practices.