# How to Enable Debug Mode in Snipe-IT: A Complete Configuration Guide

> Learn how to enable debug mode in Snipe-IT by setting APP_DEBUG to true in your .env file. Follow our guide for temporary production troubleshooting.

- Repository: [Grokability, Inc./snipe-it](https://github.com/grokability/snipe-it)
- Tags: how-to-guide
- Published: 2026-07-31

---

**Set `APP_DEBUG=true` in your `.env` file, run `php artisan config:clear`, and ensure you only enable it in production temporarily for troubleshooting.**

Snipe-IT is an open-source IT asset management platform built on **Laravel 12**. When you need to troubleshoot errors, view detailed stack traces, or inspect configuration issues, knowing how to enable debug mode in Snipe-IT becomes essential for developers and system administrators.

## Understanding Laravel Debug Configuration in Snipe-IT

Snipe-IT leverages Laravel’s standard configuration system to control error reporting verbosity. The debug flag resides in [`config/app.php`](https://github.com/grokability/snipe-it/blob/main/config/app.php) at line 137, where it reads the `APP_DEBUG` environment variable and defaults to `false`:

```php
// config/app.php
'debug' => env('APP_DEBUG', false),

```

The repository ships with a template environment file at `.env.example` (line 5) that explicitly disables debugging to prevent accidental exposure of sensitive data in production environments.

## Step-by-Step: Enable Debug Mode in Snipe-IT

### 1. Update the Environment File

Locate your `.env` file in the project root and modify the `APP_DEBUG` value:

```text

# .env

APP_DEBUG=true

```

If you are starting from the example file, note that `.env.example` contains `APP_DEBUG=false` as the default safe configuration.

### 2. Clear Configuration Cache

Laravel caches configuration values for performance. After modifying `.env`, you must clear the cache to load the new debug setting:

```bash
php artisan config:clear
php artisan cache:clear   # optional but recommended

```

Without running `config:clear`, the application continues using the cached value where debug mode remains disabled.

### 3. Verify the Production Warning Banner

When debug mode is active and the application environment is set to `production`, Snipe-IT displays a prominent red warning banner at the top of every page. This safety feature is implemented in [`resources/views/layouts/default.blade.php`](https://github.com/grokability/snipe-it/blob/main/resources/views/layouts/default.blade.php) (lines 817-823) and renders when `config('app.debug')` returns `true` while `APP_ENV=production`.

Open any authenticated page in your browser to confirm:
- **Debug enabled**: Detailed error pages with stack traces appear when exceptions occur
- **Production warning**: A banner displays the message *“Yikes! You should turn off debug mode unless you encounter any issues…”* (sourced from translation files)

## Programmatic Detection and Testing

You can check debug status programmatically within controllers, services, or custom commands:

```php
if (config('app.debug')) {
    // Debug mode is active – enable extra logging
    Log::debug('Verbose debugging enabled for troubleshooting');
}

```

The codebase includes automated tests to verify this behavior. Run the specific test that validates the warning banner logic:

```bash
php artisan test --filter=ShowSetUpPageTest

```

This test asserts that the warning appears only when `APP_DEBUG=true` **and** `APP_ENV=production`, ensuring the safety mechanism functions correctly across deployments.

## Security Considerations

Enabling debug mode in **production environments** exposes sensitive configuration details, environment variables, and file paths to end users. Snipe-IT mitigates this risk through:

- **Visual warnings**: The banner in [`resources/views/layouts/default.blade.php`](https://github.com/grokability/snipe-it/blob/main/resources/views/layouts/default.blade.php) and [`resources/views/setup/index.blade.php`](https://github.com/grokability/snipe-it/blob/main/resources/views/setup/index.blade.php) (line 152) alerts administrators when debug mode remains active
- **Environment checks**: The warning logic specifically targets production environments to avoid distracting developers working locally

**Best practice**: Enable debug mode only during active troubleshooting sessions. Once you resolve the issue, immediately set `APP_DEBUG=false`, run `php artisan config:clear`, and verify the warning banner disappears.

## Summary

- **Configuration location**: Debug mode is controlled by the `APP_DEBUG` environment variable read from [`config/app.php`](https://github.com/grokability/snipe-it/blob/main/config/app.php) (line 137)
- **Enable procedure**: Set `APP_DEBUG=true` in `.env`, then execute `php artisan config:clear` to apply changes
- **Safety features**: Production deployments display a warning banner defined in [`resources/views/layouts/default.blade.php`](https://github.com/grokability/snipe-it/blob/main/resources/views/layouts/default.blade.php) (lines 817-823) when debug is active
- **Testing**: The [`ShowSetUpPageTest.php`](https://github.com/grokability/snipe-it/blob/main/ShowSetUpPageTest.php) test suite validates warning banner behavior
- **Security**: Never leave debug mode enabled in production; it exposes sensitive application data through detailed error pages

## Frequently Asked Questions

### Where is the debug setting stored in Snipe-IT?

The debug setting is stored in the `APP_DEBUG` environment variable, which is read by [`config/app.php`](https://github.com/grokability/snipe-it/blob/main/config/app.php) at line 137. The actual value resides in your `.env` file, not in the committed configuration files.

### Why do I see a red warning banner after enabling debug mode?

Snipe-IT renders a warning banner in [`resources/views/layouts/default.blade.php`](https://github.com/grokability/snipe-it/blob/main/resources/views/layouts/default.blade.php) (lines 817-823) whenever `config('app.debug')` is `true` and the application environment is `production`. This alerts administrators that sensitive error details may be visible to users.

### Do I need to restart the web server after changing APP_DEBUG?

No, you do not need to restart Apache, Nginx, or PHP-FPM. However, you must run `php artisan config:clear` to flush Laravel's cached configuration. If you are using OPcache, you may also need to reload PHP or clear the OPcache for changes to take effect immediately.

### Is it safe to enable debug mode in production temporarily?

While possible, enabling debug mode in production exposes stack traces, environment variables, and file paths to anyone who triggers an error. Snipe-IT shows a prominent warning banner to remind you to disable it immediately after troubleshooting. Always set `APP_DEBUG=false` and clear the config cache as soon as you finish debugging.