troubleshooting.md

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.

1. 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.

2. 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: