Skip to main content
Every installer failure stops with a message that names the cause, plus the location of a log file. Find the message below. When asking Timbal for help, send the message you saw and these log files.

​
Installer messages

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. Configuring a proxy doesn’t help: the service connects directly.
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).
The connection reaches a proxy or intrusion-prevention system that removes the WebSocket upgrade. Ask IT to allow WebSocket traffic to api.timbal.ai.
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.
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.
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 and run it unchanged.
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.
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.
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.
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.
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

The service is installed but can’t keep a connection to Timbal. Run doctor on the server, and check the network requirements from the server itself. The installer checks the network once; a firewall change after installation can still break it.
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 or Re-enroll on Linux and macOS.
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.
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.
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.
In an elevated PowerShell:
Add --connection <name> to check one connection, and --connection <name> --table <schema.table> to list a table’s columns.

​
Next steps

Configure connections

Databases in connections.json, file shares in config.json.

Network requirements

The firewall rule, and how to check each layer.