Debug logging must be configured to see more detailed “debug” level logs.

Enable Debug Logging

Simply add debug to the levels in your config.yaml:

YAML 
1
2
3
4

server:
  logging:
    - output: "stdout"
      levels: "info|warning|error|debug"  # Add debug to see detailed logs

Log Levels

LevelDescription
errorOnly error messages
warningWarnings and errors
infoGeneral information (default)
debugDetailed debugging information including file/line numbers
apiAPI request/response logs (via apiLevels)

What Debug Logging Shows

When debug logging is enabled, you’ll see detailed information about:

  • HTTP request/response details
  • File operations and permissions
  • Authentication attempts
  • Database queries
  • Share creation and access
  • Integration operations (OnlyOffice, FFmpeg)
  • Exact file and line numbers for all log events

Logging Configuration Examples

Default Behavior (No Config Required)

If you don’t configure logging, you get this by default:

YAML 
1
2
3
4
5
6

server:
  port: 8080
  # No logging config = default stdout with colors and API logs
  sources:
    - path: "/data"
      name: "files"

This gives you INFO, WARNING, ERROR, and API logs to stdout with colors.

Enable Debug Logging

YAML 
1
2
3
4
5
6
7
8

server:
  port: 8080
  logging:
    - output: "stdout"
      levels: "info|warning|error|debug"
  sources:
    - path: "/data"
      name: "files"

File Output

Log to a file:

YAML 
1
2
3
4
5
6
7
8
9

server:
  port: 8080
  logging:
    - levels: "info|debug|warning|error"
      output: "/var/log/filebrowser/debug.log"
      noColors: true  # Disable colors for file output
  sources:
    - path: "/data"
      name: "files"

Structured JSON Logging

Enable JSON structured logs for log aggregation tools:

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

server:
  port: 8080
  logging:
    - levels: "info|debug|warning|error"
      output: "stdout"
      json: true    # Output in JSON format
      utc: true     # Use UTC timestamps
  sources:
    - path: "/data"
      name: "files"

Multiple Log Outputs

You can have multiple file loggers and one stdout logger:

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

server:
  port: 8080
  logging:
    # Console output without API logs
    - output: "stdout"
      levels: "info|warning|error"
      apiLevels: "disabled"
    # API events to separate file
    - output: "api-events.log"
      levels: "disabled"  # Only log API events
      noColors: true
    # Errors to separate file
    - output: "errors.log"
      levels: "error|warning"
      apiLevels: "disabled"
      noColors: true
  sources:
    - path: "/data"
      name: "files"

API-Specific Logging

Configure separate log levels for API requests:

YAML 
1
2
3
4
5
6
7
8
9

server:
  port: 8080
  logging:
    - output: "stdout"
      levels: "info|warning|error"
      apiLevels: "info|warning|error"  # API logs at different levels
  sources:
    - path: "/data"
      name: "files"

Or disable API logs entirely:

YAML 
1
2
3
4
5
6
7
8
9

server:
  port: 8080
  logging:
    - output: "stdout"
      levels: "info|warning|error"
      apiLevels: "disabled"
  sources:
    - path: "/data"
      name: "files"

Complete Production Example

For production environments, recommended logging configuration:

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

server:
  port: 8080
  baseURL: "/"
  database: "/database/database.db"
  logging:
    # Main application logs to file
    - output: "/var/log/filebrowser/app.log"
      levels: "info|warning|error"
      noColors: true
      json: true
      utc: true
    # Error-only logs for monitoring
    - output: "/var/log/filebrowser/errors.log"
      levels: "error"
      apiLevels: "disabled"
      noColors: true
      json: true
      utc: true
    # API events to separate file
    - output: "/var/log/filebrowser/api.log"
      levels: "disabled"
      apiLevels: "info|warning|error"
      noColors: true
      json: true
      utc: true
  sources:
    - path: "/data"
      name: "files"
      config:
        denyByDefault: false

auth:
  tokenExpirationHours: 2
  methods:
    password:
      enabled: true

Special Log Behaviors

FATAL Logs

Debug Mode Line Numbers

When debug logging is enabled, all log types (not just debug) will include the exact file and line number that caused the log event. This helps with troubleshooting but adds overhead.

Troubleshooting

Terminal Shows Weird Characters

If you see 033[0m or similar text in your logs:

YAML 
1
2
3
4
5
6
7
8

server:
  logging:
    - output: "stdout"
      levels: "info|warning|error"
      noColors: true  # Disable color codes
  sources:
    - path: "/data"
      name: "files"

Enable Debug Logging Temporarily

For troubleshooting, temporarily enable debug logging:

YAML 
1
2
3
4
5
6
7

server:
  logging:
    - output: "stdout"
      levels: "info|warning|error|debug"  # Add debug level
  sources:
    - path: "/data"
      name: "files"

Log Rotation

FileBrowser doesn’t handle log rotation internally. Use external tools like logrotate:

TEXT 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

/var/log/filebrowser/*.log {
    daily
    rotate 7
    compress
    delaycompress
    notifempty
    create 0640 filebrowser filebrowser
    sharedscripts
    postrotate
        systemctl reload filebrowser
    endscript
}

Next Steps