> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Installer messages, connection problems and how to fix them Every installer failure stops with a message that names the cause, plus the location of a log file. Find the message below. | Log | Where | | - | - | | Setup file (Windows) | `%TEMP%\timbal-connect-setup.log` of the user who ran it | | Setup window (Windows) | `%TEMP%\timbal-connect-setup-ui.log`, for failures before the administrator prompt | | Installer (Windows) | `C:\ProgramData\TimbalConnect\setup.log` | | Service (Windows) | `C:\ProgramData\TimbalConnect\timbal-connect.log` | | Service (Linux) | `journalctl -u timbal-connect` | | Service (macOS) | `/Library/Logs/timbal-connect.log` | When asking Timbal for help, send the message you saw and these log files. ## Installer messages > [accordion] Cannot reach api.timbal.ai:443 / Timed out connecting > > The server can't open a connection to Timbal: a firewall blocks (refused) or silently drops (timed out) outbound port 443. Ask IT for the rule in [Network requirements](https://docs.timbal.ai/connect/network-requirements.md#what-to-send-your-it-team). Configuring a proxy doesn't help: the service connects directly. > [accordion] The certificate is issued by ..., not by a public CA / TLS handshake failed > > A firewall on your network inspects TLS traffic and presents its own certificate instead of Timbal's. The connector only trusts public certificate authorities, so it would never connect. Ask IT to exclude `api.timbal.ai` from TLS inspection (SSL inspection / HTTPS decryption). > [accordion] refused the WebSocket upgrade > > The connection reaches a proxy or intrusion-prevention system that removes the WebSocket upgrade. Ask IT to allow WebSocket traffic to `api.timbal.ai`. > [accordion] DNS lookup for api.timbal.ai failed > > The server can't resolve public host names. Check its DNS servers, or ask IT whether servers in that network resolve external names at all. > [accordion] PowerShell runs in ConstrainedLanguage mode / Group Policy enforces the AllSigned execution policy > > Application control (AppLocker, WDAC or Device Guard) or Group Policy blocks unsigned PowerShell scripts, which the setup file relies on. Install the connector binary directly instead: [Locked-down servers](https://docs.timbal.ai/connect/install-windows.md#locked-down-servers). > [accordion] This file is incomplete: it is missing its embedded installer > > The setup file was changed on the way to the server: edited, re-saved with a different encoding, or passed through a chat app, email body or AI assistant. Download a fresh copy directly from [`TimbalConnectSetup.cmd`](https://api.timbal.ai/v1/connect/releases/TimbalConnectSetup.cmd) and run it unchanged. > [accordion] Unknown argument / needs a value > > The command line has a typo. Options start with a single dash (`-Token`, not `--token`) and each one except `-SkipNetworkCheck` takes a value. See [Scripted install](https://docs.timbal.ai/connect/install-windows.md#scripted-install). > [accordion] Could not unpack the installer embedded in this file > > The setup file couldn't write to your temp folder. Check that `%TEMP%` exists and is writable, and that antivirus isn't quarantining files written there. > [accordion] Administrator rights are required and were denied > > The administrator prompt was declined or the account isn't a local administrator. Run it again and accept the prompt, or ask an administrator to run it. > [accordion] The console window opens and closes immediately > > Older versions of the setup file could exit without a message, usually on servers that block PowerShell scripts or when the file was altered in transit. Download a fresh copy: the current version always stops and explains what went wrong. On a server that blocks PowerShell, go straight to [Locked-down servers](https://docs.timbal.ai/connect/install-windows.md#locked-down-servers). > [accordion] Windows protected your PC / nothing happens on double-click > > Windows marks downloaded files as coming from the internet. Right-click the file, choose **Properties**, tick **Unblock**, then **OK**, and run it again. ## After installing > [accordion] The connector shows as offline in Timbal > > The service is installed but can't keep a connection to Timbal. Run [`doctor`](#run-doctor) on the server, and check the [network requirements](https://docs.timbal.ai/connect/network-requirements.md) from the server itself. The installer checks the network once; a firewall change after installation can still break it. > [accordion] The log says: invalid or expired enrollment token > > The token is older than its lifetime (24 hours by default), was already used by another installation, or belongs to a different environment than the one selected during setup. Create a new token and run the installer again with it: on a server that already has Timbal Connect, a new token re-enrolls it. See [Re-enroll on Windows](https://docs.timbal.ai/connect/install-windows.md#re-enroll) or [Re-enroll on Linux and macOS](https://docs.timbal.ai/connect/install-linux-macos.md#re-enroll). > [accordion] Login failed for user 'CORP\SERVERNAME\$' > > The service runs as `NetworkService`, which reaches SQL Server on another machine as the computer account. Run the service as a domain account and grant it a login: [SQL Server authentication](https://docs.timbal.ai/connect/connections.md#sql-server-authentication). > [accordion] connections.json doesn't parse > > Usually a byte-order mark: save the file as UTF-8 **without** BOM. Also check that backslashes are doubled inside strings (`"CORP\\svc"`). `doctor` prints the exact parse error. > [accordion] A SQL Server named instance doesn't connect > > `Server=host\INSTANCE` needs the SQL Browser service and UDP 1434. If either is off or firewalled, use the instance's port instead: `Server=tcp:host,PORT`. ## Run doctor `doctor` is a read-only check you can run any time on the server. It validates the configuration, checks that the server can reach Timbal, connects to every database in `connections.json`, and checks each file share in `config.json`. It exits with a non-zero code if anything fails. > [tab] Windows > > In an elevated PowerShell: > > ```powershell theme={"dark"} > & "$env:ProgramFiles\TimbalConnect\current\timbal-connect.exe" doctor > ``` > [tab] Linux > > ```bash theme={"dark"} > sudo bash -c 'set -a; . /etc/timbal-connect/connector.env; exec /opt/timbal-connect/current/timbal-connect doctor' > ``` > [tab] macOS > > ```bash theme={"dark"} > sudo /opt/timbal-connect/current/timbal-connect doctor > ``` Add `--connection ` to check one connection, and `--connection --table ` to list a table's columns. ## Next steps > [card] [Configure connections](https://docs.timbal.ai/connect/connections.md) > > Databases in `connections.json`, file shares in `config.json`. > [card] [Network requirements](https://docs.timbal.ai/connect/network-requirements.md) > > The firewall rule, and how to check each layer. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.