#Troubleshooting

#Authentication

#"Your token for gitlab.example.com expired"

Since GitLab 16.0 every access token has an expiry. If you left it blank when creating one, it is 365 days out, and personal access tokens expire at 00:00 UTC on their date.

The message names the instance and links the exact creation URL for it. Create a new token and:

labdash auth login --hostname gitlab.example.com --with-token

An OAuth credential from labdash auth login renews itself and does not reach this state. If one does, the stored refresh token was invalidated, and logging in again is the fix.

You should have had warning. A context-bar notice appears fourteen days before a token expires and becomes prominent at three. If a token dies while the dashboard is open, one key restarts the login in place and the sections resume with your scroll position and pinned tabs intact, so there is nothing to restart.

#The browser says "Device successfully authorized" and then shows the form again

The login worked. GitLab re-renders its empty device-code form after authorising, which reads as a second prompt.

That is GitLab's page, and RFC 8628 has no redirect to request. Check your terminal: the token is already there. More.

#Actions return 403 but reading works

Your token carries the read_api scope. That is read-only mode, working as intended.

To act on rows, create a token with the api scope. If you meant to be read-only, nothing is wrong, and the mutating keys are already absent from the footer.

#auth status shows a token but requests fail with 401

Check which credential is in use. Resolution is, per instance:

1. That instance's tokenEnv
2. GITLAB_TOKEN / GITLAB_ACCESS_TOKEN / OAUTH_TOKEN, on the default host only
3. The credential store

An exported GITLAB_TOKEN from another project beats your stored credential on the default host. labdash auth status names the source.

#Logging in on a self-managed instance does nothing useful

Your GitLab has no OAuth application registered, and labdash's gitlab.com application ID means nothing there. Use a token:

labdash auth login --hostname gitlab.example.com --with-token

Or ask an administrator to register an application.

#Connection

#x509: certificate signed by unknown authority

Your instance uses a private certificate authority. Point at its root certificate:

instances:
  gitlab.example.com:
    caCert: /etc/ssl/certs/corp-root.pem

Avoid insecureSkipVerify: true. Behind a TLS-inspecting corporate proxy, disabling verification is a real risk rather than a theoretical one. Finding your CA certificate.

#Every request returns 404

Usually a subfolder problem: missing when GitLab lives at https://example.com/gitlab/, or set when it does not.

instances:
  gitlab.example.com:
    subfolder: gitlab

#It hangs and then times out

A proxy is required and not configured:

instances:
  gitlab.example.com:
    proxy: http://proxy.internal:3128

HTTPS_PROXY from your environment is also honoured. An explicit proxy: overrides it.

#One section shows an error and the others are fine

Failure is per section, so one slow or broken query leaves the rest of the dashboard alone.

r retries it. d shows the full error with the request id.

#Display

#Boxes, question marks, or ▯ instead of icons

Your terminal font is missing a glyph. labdash uses ordinary Unicode rather than a patched font, so this is rare, and old bitmap fonts and some Linux virtual consoles are where it happens. Force the fallback:

theme:
  icons: ascii

Columns line up identically. Every glyph is one cell and every ASCII replacement is one character.

#Columns are misaligned

Usually a glyph drawn two cells wide where labdash measured one. Three of the status glyphs are classed as East Asian Ambiguous, which means a terminal set up for CJK text draws them double-width.

theme: { icons: ascii } confirms it in one step: if the alignment fixes itself, glyph width is the cause. auto already picks ascii on a CJK locale, so seeing this means the locale did not say so.

If it persists with ASCII icons, report it with your terminal name and version.

#The screen is smeared, or text is left behind

Usually a subprocess writing to the terminal. labdash sends every subprocess's output to io.Discard, so this is a bug. Report it with the action you took.

Ctrl+R forces a full repaint in the meantime.

#Everything is monochrome

Something set NO_COLOR. labdash honours it unconditionally and no setting overrides it.

echo $NO_COLOR

#"Terminal too narrow"

Below 56 columns there is not enough room for a usable table. Between 56 and 79 you get a single pane with three columns, and the preview goes full-screen on Enter. Breakpoints.

#Views and filters

#A tab is empty and you expected rows

In order of likelihood:

1. The filter is stricter than you think. The empty state restates the query that produced it. Read it, then press f to loosen it.
2. draft:false is hiding them. Half a busy queue is drafts.
3. The scope is narrower than you meant. The breadcrumb in the context bar says where you are. Press b and pick a parent group.
4. The date filter is too recent. updated < 24h on a quiet group returns nothing.

A mistyped value is not the cause: the filter bar rejects an invalid enum at the keystroke and completes label, user and project names from your own instance.

#A pinned tab disappeared

P on a pinned tab unpins it and offers an undo immediately. Once the undo has gone, rebuild it with b, f, P.

If every tab is gone, the state file was reset. That happens only when it could not be read, and labdash says so on startup. Your credential and settings are unaffected.

#Launching inside a repository changed what I see

labdash reads the git remote and starts the browse tree at that project. Press Ctrl+G to toggle it off, or b to go anywhere else. Your pinned tabs are unaffected.

#Settings

#A settings change did nothing

Check which file is in use:

labdash settings path

--config and LABDASH_CONFIG both outrank the user settings file.

Settings hold connection details only: which GitLab, how to reach it, where your clones are, and how the interface looks. What appears in a table comes from browsing, filtering and pinning. See settings.

#Startup is slow on a self-managed instance

Group pipeline views fan out across every project beneath the group, which makes them the most expensive query in the product. labdash bounds the fan-out itself, and a large group still returns.

If a group is big enough to be slow, scope narrower: browse one level down and pin that instead. A subgroup you work in daily loads faster than a tree you have to scan.

#Deeper diagnostics

labdash doctor
LABDASH_DEBUG_HTTP=1 labdash

The debug log redacts Authorization, PRIVATE-TOKEN and JOB-TOKEN before writing. See diagnostics.