Debugging

Tuist provides several tools to help you diagnose issues when commands don't behave as expected.

Warning

Session data may contain sensitive information such as file paths, project names, and request/response bodies. While sensitive headers (like Authorization) are redacted, be mindful when sharing session data with others.

Session data#

If a command invocation doesn't yield the intended results, you can diagnose the issue by inspecting the session data. The CLI forwards the logs to OSLog and the file-system.

In every run, it creates a session directory at $XDG_STATE_HOME/tuist/sessions/{uuid}/ where $XDG_STATE_HOME takes the value ~/.local/state if the environment variable is not set. You can also use $TUIST_XDG_STATE_HOME to set a Tuist-specific state directory, which takes precedence over $XDG_STATE_HOME.

Each session directory contains:

logs.txt - Text logs from the CLI session
network.har - HTTP Archive (HAR) file containing all network requests and responses made during the session

Visualizing HAR files#

The HAR file records all HTTP requests and responses made during the session, which is useful for debugging server communication issues. You can open HAR files with several tools:

Proxyman: A native macOS app for viewing and analyzing HTTP traffic. Import the HAR file via File > Import.
Browser Developer Tools: Chrome, Firefox, and Safari all support importing HAR files in their Network tab.
HAR Viewer: A web-based HAR file viewer.

Tip

Learn more about Tuist's directory organization and how to configure custom directories in the Directories documentation.

By default, the CLI outputs the session path when the execution exits unexpectedly. If it doesn't, you can find the session data in the path mentioned above (i.e., the most recent session directory).

Session directories older than 5 days are automatically cleaned up. Tuist also keeps at most 50 inactive session directories by default, while preserving sessions owned by currently running Tuist processes. In CI environments that run many Tuist commands with the same state directory, you can raise the inactive-session cap with TUIST_SESSION_MAX_SESSIONS, for example TUIST_SESSION_MAX_SESSIONS=200. Invalid values, zero, and negative values are ignored and Tuist falls back to the default of 50.

Continuous integration#

In CI, where environments are disposable, you might want to configure your CI pipeline to export Tuist session data. Exporting artifacts is a common capability across CI services, and the configuration depends on the service you use. For example, in GitHub Actions, you can use the actions/upload-artifact action to upload the session data as an artifact:

yaml

name: Node CI

on: [push]

env:
  TUIST_XDG_STATE_HOME: /tmp

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # ... other steps
      - run: tuist generate
      # ... do something with the project
      - name: Export Tuist session data
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: tuist-sessions
          path: /tmp/tuist/sessions/

Cache daemon debugging#

For debugging cache-related issues, Tuist logs cache daemon operations using os_log with the subsystem dev.tuist.cache. You can stream these logs in real-time using:

bash

log stream --predicate 'subsystem == "dev.tuist.cache"' --debug

These logs are also visible in Console.app by filtering for the dev.tuist.cache subsystem. This provides detailed information about cache operations, which can help diagnose cache upload, download, and communication issues.

Tuning network timeouts#

All of Tuist's HTTP traffic—server API calls, the registry, previews, and cache artifact transfers—goes through a shared URLSession with sensible defaults. On slow or congested network paths (for example, a self-hosted setup reaching object storage through a corporate proxy), an individual request can starve and hit the resource timeout before it completes. For cache downloads in particular, hitting the timeout makes Tuist fall back to building the module from source, which is far more expensive than waiting a bit longer for the cached binary. You can tune the underlying HTTP settings through environment variables, with the defaults applied when they're unset or set to an invalid value:

bash

# Maximum time (in seconds) a single resource transfer can take before it's cancelled (default: 90)
export TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE=600

# Maximum time (in seconds) to wait for new data on an existing request (default: 120)
export TUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUEST=300

# Maximum number of simultaneous connections per host (default: 20)
export TUIST_HTTP_MAXIMUM_CONNECTIONS_PER_HOST=40

Raising TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE lets a recoverable-but-slow download finish instead of timing out—for cache downloads, that means landing a cache hit rather than falling back to a build from source.