> For the complete documentation index, see [llms.txt](https://skyforgeai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skyforgeai.gitbook.io/docs/reference/troubleshooting.md). # Troubleshooting Symptoms grouped by where they show up. If you're setting OAuth up for the first time, [Connecting to ServiceNow → OAuth 2.0](/docs/connect/servicenow-connection.md#oauth-20) has the field-by-field walkthrough. *** ## Install & startup | Problem | Fix | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `skyforge` not recognized (Windows) | Add `%APPDATA%\npm` to your PATH — see [Installation](/docs/start-here/installation.md#install) | | Silent failures in analytics or auth | Directory permissions — run the check in [Installation](/docs/start-here/installation.md#check-directory-access) | | Web UI file attach not working | Must be on `localhost` or HTTPS | > ⚠️ **Never run `skyforge` with `sudo`.** Running as root creates root-owned files; your normal user then loses access and analytics stop working. *** ## ServiceNow authentication ### OAuth errors | Error | Fix | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OAuth refresh token flow failed: 401` | Refresh Token Lifespan is `0` — set to `8640000`, then re-authenticate | | `Access to unscoped api is not allowed` (403) | Scope restriction is on. Application Registry: set `Broadly scoped`. New Inbound Integration Experience: uncheck **Allow access only to APIs in selected scope** *and* **Enforce token restriction** | | `Invalid redirect_uri` | Redirect URL must be exactly `http://localhost:3005/callback` — no trailing slash, no `https` | | Client secret rejected | **This is a public client** is checked — uncheck it | Full field reference for both ServiceNow UIs: [Connecting to ServiceNow → OAuth 2.0](/docs/connect/servicenow-connection.md#oauth-20). ### Basic Auth errors | Error | Fix | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 on every call, credentials correct | Australia release or newer requires the `snc_basic_auth_api_access` role on the account — see [Connecting to ServiceNow](/docs/connect/servicenow-connection.md#basic-auth) | ### SSO / Browser Session errors | Error | Fix | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Session verification failed: HTTP 401` | Session expired — copy a fresh cURL from DevTools and re-authenticate | | Connects fine, but every API call returns 401 | Australia release or newer requires the `snc_basic_auth_api_access` role on the account — SSO login alone isn't enough. See [Connecting to ServiceNow](/docs/connect/servicenow-connection.md#browser-session--sso) | | `No cookies in cURL` | Wrong request copied — filter DevTools by `api/now/table/` | | MCP tools not available after connecting | Restart SkyForge | ### After changing anything in ServiceNow Changes don't reach SkyForge until you re-authenticate. Hub → **Instance** tab → **Edit** → re-enter credentials → **Save Changes**. If the instance is wedged, **Remove** it and add it again. *** ## Corporate proxy / TLS certificate errors If every network call fails with a certificate/TLS error (e.g. `unable to verify the first certificate`, `self signed certificate in certificate chain`), you're most likely on a corporate laptop where a security/inspection proxy re-signs HTTPS traffic with its own certificate authority (CA) — a certificate that's trusted by your OS but not by SkyForge's own Node/Bun runtime. **Preferred fix — trust the corporate CA specifically:** ```bash export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem" skyforge ``` Ask your IT/security team for the CA certificate file if you don't already have it. This keeps certificate verification on for everything else and only extends trust to your own organization's proxy. **Quick workaround — disable verification entirely:** ```bash export NODE_TLS_REJECT_UNAUTHORIZED=0 skyforge ``` or one-off, no persistence: ```bash NODE_TLS_REJECT_UNAUTHORIZED=0 skyforge ``` (PowerShell: `$env:NODE_TLS_REJECT_UNAUTHORIZED="0"; skyforge`, or set it persistently via Windows key → "Environment Variables" → *Edit environment variables for your account*.) > ⚠️ **Know what this does before using it.** This makes SkyForge accept *any* TLS certificate for *any* HTTPS connection it makes — not just your corporate proxy's, but a malicious one too if you're ever on a hostile network (public wifi, compromised DNS, etc.). It's a blanket, machine-wide bypass, not scoped to just the corporate proxy. If a laptop configured this way ever leaves the corporate network/VPN, it stays silently unprotected against TLS interception on any other network. Prefer `NODE_EXTRA_CA_CERTS` above when you can. **Scoping the workaround to just SkyForge:** SkyForge's MCP server loads a `.env` file from the current working directory (and falls back to the parent directory's `.env` if none is found) via `dotenv` — it does not read one from `~/.config/skyforge/`. So instead of a machine-wide environment variable, you can place a project-local `.env` file (containing `NODE_TLS_REJECT_UNAUTHORIZED=0`) in the directory you run `skyforge` from, limiting the bypass to sessions started from that folder rather than every process on the machine. *** ## Tools & MCP | Problem | Fix | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Tool not found` | Tools are lazy-loaded — type `search for X tools` first | | MCP not connecting | `tail -f ~/.skyforge/skyforge-mcp.log`, or restart with debug logging on: `SN_MCP_DEBUG=true skyforge` (macOS/Linux), `$env:SN_MCP_DEBUG="true"; skyforge` (PowerShell) | | Claude Desktop shows the server as failed | Install `mcp-remote` globally rather than using `npx` — see [SkyForge in Claude Desktop](/docs/extend/claude-desktop.md#troubleshooting) | Log file locations for every platform: [Running SkyForge → Logs](/docs/use/running-skyforge.md#logs). *** ## Reset to clean state Removes all config, credentials, analytics, and cached data. You'll need to reconnect your instance and AI provider afterwards. The supported way is the built-in command, which knows every directory SkyForge creates: ```bash skyforge uninstall # remove everything skyforge uninstall --dry-run # show what would go, remove nothing skyforge uninstall --keep-config # leave skyforge.jsonc in place skyforge uninstall --keep-data # leave session data and snapshots ``` To do it by hand instead: **macOS / Linux:** ```bash rm -rf ~/.config/skyforge rm -rf ~/.local/share/skyforge rm -rf ~/.local/state/skyforge rm -rf ~/.cache/skyforge rm -rf ~/.skyforge rm -rf ~/.local/share/opentui ``` **Windows (PowerShell):** ```powershell Remove-Item -Recurse -Force "$env:USERPROFILE\.config\skyforge" Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\skyforge" Remove-Item -Recurse -Force "$env:USERPROFILE\.local\state\skyforge" Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\skyforge" Remove-Item -Recurse -Force "$env:USERPROFILE\.skyforge" Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\opentui" ``` > `~/.local/state/skyforge` is created at startup alongside the other four but was missing from these lists, so a "clean" reset left state behind. `skyforge uninstall` has always covered it. Then reinstall: ```bash npm i -g @skyforgeai/skyforge@latest skyforge ``` *** ## Need help? [Submit an issue →](https://github.com/tryskyforge/skyforgeissues)