Troubleshooting cache volumes

Debugging issues that involve cached data is difficult because the workflow environment can change between runs. To inspect a cache volume directly, you can attach it to a one-off instance.

Connecting to cache volumes

Namespace allows you to create one-off instances and connect them to a cache volume.

Create an instance

Using nsc create —volume, you can create an instance and attach a cache volume.

nsc create --volume cache:<cache-tag>:/cache:<size>gb

The size and the tag should match what you see on the dashboard.Note: this follows standard cache volume semantics. Namespace tries hard to provide you with the latest cache version, but you may rarely see a slightly stale cache instead.

Connect via SSH

nsc ssh <instance>

Inside the instance, you can find the cache contents at the mount point:

ls -al /cache

Setting breakpoints

When you want to investigate a particular cache state, you can temporarily add a breakpoint to your workflow definition and jump into an interactive SSH session.

jobs:
  tests:
    runs-on: namespace-profile-with-caching

    steps:
      - uses: actions/checkout@v4

      - uses: namespacelabs/nscloud-cache-action@v1
        with: ...

      - name: Run tests
        shell: bash
        run: ...

      - name: Breakpoint if tests failed
        if: failure() # Remove this for an unconditional breakpoint
        uses: namespacelabs/breakpoint-action@v0
        with:
          duration: 15m
          authorized-users: <your-github-username>,<another-github-username>

For the full breakpoint mechanism, including breakpoint-action’s options, duration, and authorized-users, see Debugging: Interactive access.

Next steps

Hands-on support

Got stuck? Need help with debugging one of your workflows? Our team is here to assist:

Technical support: Reach out to support@namespace.so to talk to one of our engineers.
Community: Join our community Discord to learn about tips and best practices.

Last modified on September 15, 2026

⌘I

Products

Platform

Administration

Connecting to cache volumes

Create an instance

Connect via SSH

Setting breakpoints

Next steps

Hands-on support

​Connecting to cache volumes

Create an instance

Connect via SSH

​Setting breakpoints

​Next steps

​Hands-on support

Connecting to cache volumes

Setting breakpoints

Next steps

Hands-on support