Repository navigation
Troubleshooting
github-actions[bot] edited this page Oct 30, 2026
·
3 revisions
Symptom-first answers for the failures seen so far: issues reported from consumer deployments (anonymized, with the package version that fixed each), the web app, the desktop app, and the local development environment. Each entry gives the symptom, the cause and the fix, then points at the repo section with the full story. The operational procedures themselves are indexed on Runbooks; upgrade steps are on Deploy and Upgrade.
- Symptom: "Get credentials" and console links for one role return a 502; other roles in the same account keep working.
- Cause: the role's session length in the portal catalog (for example 12 h) exceeds the IAM role's
MaxSessionDuration. Packages before 0.1.2 created target roles with a 1 h cap, so STS refused with "The requested DurationSeconds exceeds the MaxSessionDuration set for this role" and the API mapped that to a generic 502. - Fix: fixed in 0.1.2, which creates target roles with a 12 h
MaxSessionDuration; redeploy theAccessTarget-*stacks. Without the upgrade, set the role's session length back to 60 minutes in Admin → Accounts. The role form's Test button runs exactly this STS check before saving. See Cross-account: trust a second account.
CredsStack update fails with "CloudWatch Logs role ARN must be set in account settings to enable logging"
- Symptom:
cdk deploy CredsStackfails on the API stage while upgrading to 0.1.2; empty log groups are left behind by the rollback, and admin pages error until the API is on the same version as the web app. - Cause: 0.1.2 enabled access logging on the vending API. A consumer
cdk.jsonwith@aws-cdk/aws-apigateway:disableCloudWatchRoleset totruestops CDK from creating the account-level CloudWatch role the stage needs; the package did not set it explicitly. - Fix: fixed in 0.1.3, which sets
cloudWatchRole: trueso the role ships with CredsStack regardless of the consumer's flags. Retrying is safe; delete the orphaned empty log groups by hand. Deploy the hub stacks together, as Upgrade says.
- Symptom: before 0.1.4 every consumer had to invent a
githubRepovalue; from 0.1.4 the deployment fails its type check while the field is still present (an unknown property in the object literal). - Cause: the field only fed FNTIO's own pipeline stack, which is not part of the package.
- Fix: fixed in 0.1.4, which removes the field. Delete
githubRepofrom your config.
- Symptom: a Security Hub CSPM run against a stock deployment fails the "associated with a WAF" controls for the API stage and the CloudFront distribution, plus by-design findings for the same resources.
- Cause: no web ACLs shipped before the
wafblock existed. - Fix: fixed in 0.1.6, which adds
ProjectConfig.waf, on by default. Bootstrap us-east-1 in the hub account before that deploy, deploy CredsStack and WebStack (WebCertStack rides along), then suppress the by-design findings once per account by workflow status. Steps in Accepted findings; background in Security Posture.
- Symptom: a WebStack deploy finishes green and the site still serves the previous Angular bundle.
- Cause: the S3 upload or CloudFront invalidation can silently leave the previous bundle in place; a green deploy is not proof.
- Fix: curl the site and check that the
main-*.jshash changed, then runcd frontend && npm run e2eagainst the live site. See Build + deploy.
- Symptom: the app lands on
/loginafter a long sleep. - Cause:
AuthServicerenews the session 60 s before the hourly expiry and re-checks when the tab becomes visible or the network returns, so a short sleep survives. Only Cognito rejecting the refresh token, at its hard 12 h validity, clears vended credentials and sends you to/login. - Fix: sign in again; the 12 h wall is by design. Details in Auth & session lifecycle.
- Symptom: the desktop app was left open past the 12 h session (often overnight, on the Network page) and now shows a red
Missing bearer tokennotice instead of the sign-in page. It reads like an account problem; it is not. - Cause: at the 12 h wall the app asked the desktop shell to drop the VPN in the same instant it was fetching the sign-in page; that fetch failed with the interface change, the page stayed signed out, and its background refresh surfaced the API's own 401 wording. Fixed in 0.1.12: the app moves to the sign-in page before the purge, the sign-in page needs no fetch, a failed hand-off falls back to a full page load, and a 401 that outlives the session reads "Your session has ended".
- Fix: on an older version, quit via the tray icon (Quit and remove credentials) and relaunch, then sign in; you return to the page you were on. Details in Session end.
- Symptom: a request keeps returning 401 after an auth change.
- Cause: the API is fronted by CloudFront and a cached 401 can linger. A 401 carrying
x-amzn-errortypeand nox-powered-by: Expresscame from API Gateway, not the app. - Fix: add
?n=123to the URL to bypass the cache. Request trails (request→requireAuth→ALLOWED/DENIED→SUCCESS) are in the vending API Lambda's CloudWatch log group; see Debugging.
- Symptom: a request is blocked with 403, or answered 429 with
Retry-After. - Cause: a WAF rule. A 429 is one of the two rate rules (
RateLimitper IP,TokenRateLimitper bearer token); a 403 is a managed rule. - Fix: read the
aws-waf-logs-<prefix>-weblog group (us-east-1) first, then-api; the log line names the rule. Raisewaf.rateLimitorwaf.perTokenRateLimitonly for a legitimately large client. See What deploys (default on).
- Symptom: calls to a route the running deploy adds return 403, and the authorizer's log line says
route-unknown; routes that existed before keep working. - Cause: the gateway method goes live before the catalog record that names it; the activation resource is written after the methods.
- Fix: wait for the deploy to finish. Ship the UI that calls a new route in the same deploy as the route, never ahead of it. See Troubleshooting under Plugins in the package README.
- Symptom: the plugin page or one of its files answers 403 under
/plugin-assets/…, and the portal reports the page never connected. - Cause: the assets path is CloudFront over a private bucket with a GetObject-only policy and no SPA rewrite, so a missing key answers 403, never
index.html. The object key must equal the URL path; the usual cause is a plugin registered with its frontend not built, or anentrynaming a file outside the built directory. - Fix: build the plugin frontend before synth, check
entry, redeploy. See Troubleshooting in the package README.
- Symptom: a plugin page shows this notice instead of loading.
- Cause: the frame and the portal speak different message protocol versions (a page built on the 0.1.x plugin packages against a 0.2.0 or later portal, or the reverse).
- Fix: rebuild the plugin against the plugin packages of the installed package version and redeploy. See Versioning in the SDK README and the 0.2.0 note on Deploy and Upgrade.
- Symptom: the frame stays blank or renders, then the portal reports a handshake timeout.
- Cause: the page never posted
ready: theentrypath names the wrong file, or the Content-Security-Policy on plugin assets blocked a script the page needs — that policy allows the portal only, so a bundle loading anything from a third-party host never runs. - Fix: open the frame URL in a tab and read the console for CSP violations; bundle every dependency; correct the entry. See Browser SDK in the SDK README and Troubleshooting in the package README.
- Symptom: a plugin request fails with 401 and the plugin shows an error, or the frame gives way to the portal's session-ended page.
- Cause: the host owns the session; the SDK never signs in itself. After an authentication-layer 401 it asks the host to renew and retries exactly once; after that the plugin surfaces the error and the portal's session-end flow applies (the 12 h wall). A plugin Lambda answering 401 for a business failure triggers the same retry.
- Fix: sign in again. Plugin authors answer domain 4xx codes, never 401. See Browser SDK in the SDK README and Troubleshooting in the package README.
- Symptom: a plain reload of a tab serves the previous bundle.
- Cause: closing the window or Cmd+Q only hides the app to the tray; the shell caches the web bundle.
- Fix: tray icon → Quit and remove credentials, then relaunch; the relaunch fetches fresh code. See Run it (development).
- Symptom: Connect appears to succeed, nothing happens, and the network pill sits on "unknown".
- Cause: the Tailscale binary is both GUI and CLI and picks CLI only when
SHLVLis set. A Dock-launched app has noSHLVL, so the CLI tried to start the GUI, printed "The Tailscale GUI failed to start (CLIError 3)" and exited 0. - Fix: current builds set
SHLVL=1on every spawn and treat that output asdaemon-not-running. Launching from a terminal (open -a "Infra Client") inherits the shell'sSHLVL. See The CLI needs SHLVL (macOS).
- Symptom: the pill offers setup instead of Connect.
- Cause: Tailscale is missing or its daemon is not running; the dialog says which.
- Fix: install Tailscale, and on macOS open it once to allow adding a VPN configuration. No Tailscale account is needed. See Connecting for the first time (end users).
- Symptom: the pill is green and a host does not answer.
- Cause: rules are still syncing (a change to your access takes up to 5 minutes; a first connection to a site starts a pass at once and takes seconds), you hold no grant, or the resource's security group does not allow the connector.
- Fix: wait out the 5 minutes, then use the resource dialog's "Test connection", which separates vpn-down from no-answer. Same section as above.
- Symptom: the connect attempt is refused.
- Cause: the single-use device key expired or was already used; the app auto-retried once.
- Fix: if it persists, an admin checks the key minter. Same section as above.
- Symptom: a machine that connected fine weeks ago cannot reach anything.
- Cause: devices offline for 7+ days expire server-side.
- Fix: click Connect again. A personal Tailscale on the same machine is a related case: one control server at a time, and Connect points the daemon at the org network; teardown only touches the app's own profiles.
- Symptom: the change is saved and the browser still runs the old code.
- Cause: a leftover
ng serveon port 4200 serves stale code and masks changes. - Fix: kill the stale dev server, then start it again.
- Symptom: npm tries to fetch
@fntio/infra-clientfrom the registry and dies. - Cause: the package is private and unpublished; only a root install links it from
packages/. - Fix: run
npm ci(ornpm install) at the repo root, never inside a workspace. See Install, test, deploy.
- Symptom: any
cdkcommand, even a barecdk bootstrap, fails at synth. - Cause: every
cdkcommand synthesizes the whole app, and WebStack needsfrontend/dist/frontend/browser/(or the copy baked into the package bynpm pack). - Fix:
npm --prefix frontend run buildbefore anycdkcommand. See Build + deploy.
- Symptom:
npm startindesktop/dies immediately; it looks like an app bug. - Cause:
ELECTRON_RUN_AS_NODE=1in the environment (shells spawned by VS Code's extension host inherit it) makesrequire('electron')return a path string instead of the API. - Fix:
env -u ELECTRON_RUN_AS_NODE npm start. Normal terminals are unaffected. See Dependency pins & overrides.
- Symptom: Gatekeeper removes the unsigned dev Electron on launch.
- Cause: a false positive on the unsigned binary; no Apple certificate is needed to run locally.
- Fix: reinstall Electron, clear quarantine and ad-hoc sign it, exactly as in macOS: "Electron … contains malware". If still blocked: System Settings → Privacy & Security → "Open Anyway".
Source: wiki/ in FNTIO/aws-infrastructure-client, mirrored by the Wiki workflow. Edit the files there; changes made on this site are overwritten by the next sync.
Start here
Use
How it works
Operate
Contribute