Skip to content

Troubleshooting

Manuel Luján edited this page Nov 6, 2026 · 1 revision

Troubleshooting

Problems documented in the README and the guides in docs/, with their fixes. If yours is not here, ask in Discussions, Q&A or open a bug report.

Web server and sign-in

The explorer opens without sign-in when I expected the sign-in screen (Windows PowerShell). $env:LINEAGE_DEMO_MODE = "1" stays set for the rest of the PowerShell session. Run Remove-Item Env:LINEAGE_DEMO_MODE before you start the server for real data from the same window. Source: README, Quick Start With Demo Data.

Everyone was signed out. Sessions live in server memory only, so a restart signs everyone out. They also expire after 8 hours idle or 24 hours in total. Source: docs/102.

Sign-in returns 429 too_many_pending_flows. Each client IP can have at most three pending device-code sign-ins. Complete or wait out the pending ones; an unfinished flow is discarded after 15 minutes. Source: docs/102.

The admin panel will not save my settings. Saving requires a non-empty tenant_id and a non-empty admin list, so that an admin cannot lock everyone out. Source: docs/102.

The user search in "Allowed users" finds nobody. The directory search needs a Microsoft Graph permission. If your tenant has not consented to it, type the email address by hand. Source: docs/102.

REST API and API keys

403 insufficient_scope when starting or stopping a scan. The API key is read_only. Scan triggers, the Warehouse upload and the OneLake publish need a full key. Source: README, REST API.

429 responses. /api/* allows 180 requests per 60-second window per client IP. Wait for the number of seconds in the Retry-After header. Source: README, REST API.

A browser-session POST from my own script is rejected because of its Origin. Cookie-authenticated POST requests must come from the server's own origin. From a script, use an API key in the X-Api-Key header instead of a session cookie. Source: docs/102.

MCP

/mcp returns 503. The mcp_http_server.py subprocess did not start. Install the MCP dependencies with pip install -r requirements-mcp.txt and check the server's startup log. The endpoint is also off when the server runs with --no-mcp-http, as in the demo image. Source: docs/110.

/mcp returns 401. The Authorization: Bearer <api-key> header is missing, or the key is invalid, expired or revoked. Every request needs it, including initialize. Source: docs/110.

claude mcp add does not accept --transport http or --header. Your version of Claude Code uses different flags. Run claude mcp add --help to see them. Source: docs/110.

The scan tools answer insufficient_scope. They need an admin-issued API key with full scope. Source: README, MCP Servers.

get_column_profile or get_column_sensitivity answers found: false. The table has not been profiled yet. Profiling only reaches Lakehouses where the service principal already has a data role. Source: docs/105.

Data shown in the viewer

The viewer shows old or local data although I configured a Warehouse or a Lakehouse. When the Warehouse or OneLake destination is not configured, or a live read fails, the server falls back to the local files. OneLake files are also cached for five minutes. Check the settings in the "Write storage" and "Explorer data (OneLake)" tabs and use their "Test connection" buttons. Source: docs/106.

A Fabric pipeline scan does not appear in the modification history. Expected: a pipeline run writes straight to the Warehouse and the Lakehouse and produces no scan diff. Source: docs/105.

A renamed item shows up as one removal and one addition. Expected: identity is the item's name, not its GUID. Source: README, Known Limitations.

The Governance panel shows a diagnostic instead of data. A permission is missing. The panel names it and the fix; the admin panel's "Tenant & auth" tab lists the extra permissions the Scanner API data needs. Source: README, Key Features and docs/102.

Fabric-native discovery

NB_Discover_Workspaces_Items sees only some workspaces. Tenant-wide discovery needs the Fabric Administrator role on the service principal. Without it, the notebook falls back to the regular Fabric API and sees only what the identity can see. Source: docs/105.

The pipeline cannot override a notebook's parameters. Mark each cell titled "Parameters" as the notebook's parameters cell ("Toggle parameter cell"). The install wizard does not do it for you. Source: docs/105.

NB_Confirm_Source_Object_Types records servers as gaps. It is the only step that connects to SQL servers outside Fabric, and it needs a network route from your capacity to them, for example through a data gateway. Unreachable servers are recorded as gaps and the rest continues. Source: docs/105.

The install wizard finished but there is no Data Pipeline. Expected: the wizard does not create the pipeline. Build it by hand in the documented notebook order. Source: docs/105.

Local scripts and containers

fab auth login fails with Unsupported method POST inside the container. Do not keep retrying the browser flow. Use the Azure CLI device-code login with -AuthMethod azure-cli:

az login --use-device-code --tenant <tenant-id> --allow-no-subscriptions
pwsh -NoLogo -File backend/scripts/01_discover_workspaces.ps1 -AuthMethod azure-cli

Source: docs/08 and docs/06.

The Fabric CLI reports an encrypted cache error inside the container. Run fab config set encryption_fallback_enabled true, then log in again. This lets the Fabric CLI store tokens without OS-backed encryption, inside the container's own auth volume only. Source: docs/08.

The Azure CLI MSI cannot be installed without administrator rights. Install it per user with pip install --user azure-cli, put that Python's scripts folder on your PATH and open a new terminal. Source: docs/06.

A build step fails because Python is missing. Scripts without the _fast suffix that have a .py twin (for example 52_build_notebook_super_lineage) are thin wrappers with no PowerShell fallback: they need python3 or python on PATH. Source: backend/scripts/README.md.

"Publish data now" fails on the server. It runs the publish script on the server, which needs pwsh there, and the caller needs can_full_scan or a full API key. Source: docs/106.

Clone this wiki locally