Troubleshooting
Find the error message you see, then follow the one-line fix. Each entry links to the page with the full explanation. For general questions, see the FAQ.
Connecting a database
Test connection fails in the admin UI
Read the hint under the form: it names the problem (refused connection, unknown host, wrong password or TLS settings). Fix that field and click Test connection again. See Admin UI → Connect a database.
A database added with faucet db add is not connected
A running server loads CLI-added databases on its next start. Run faucet stop && faucet serve, or click Test on the database row in the admin UI. See details.
Password with special characters
The admin UI fields and --password / --password-prompt need no escaping. In a DSN, URL-encode special characters (Pa@ss#1 becomes Pa%40ss%231). See details.
PostgreSQL
"password authentication failed"
Wrong username or password, or pg_hba.conf requires a different auth method for your host. More.
"no pg_hba.conf entry for host"
The server doesn't allow your client IP. Add a pg_hba.conf entry for it, or connect with sslmode=require. More.
"SSL is not enabled on the server"
Use sslmode=disable (or SSL mode Disable in the UI) for a local server, or enable SSL on the server. More.
"relation does not exist"
The table isn't in the schema Faucet is using. Check search_path or --schema. More.
MySQL and MariaDB
"Access denied for user"
Check the username, password and host; MySQL grants access per host, so localhost and 127.0.0.1 can differ. More.
"Unknown database"
The database in the connection doesn't exist. Create it with CREATE DATABASE. More.
"dial tcp: connect: connection refused"
Nothing is listening on that host and port, or a firewall blocks it. More.
Timestamps look wrong
Add loc=UTC or loc=Local to the DSN, and keep parseTime=true. More.
SQL Server
"Login failed for user"
Wrong username or password; for sa, the password must meet SQL Server's complexity rules. More.
"Cannot open server requested by the login"
The database named in the connection doesn't exist. More.
"TLS Handshake failed"
Use encrypt=disable for local development or TrustServerCertificate=true for a self-signed certificate; use a proper certificate in production. More.
SQL Server "connection refused"
SQL Server isn't running, the port is wrong, or TCP/IP is disabled in SQL Server Configuration Manager. More.
Oracle
"ORA-01017: invalid username/password"
Check the credentials (Oracle passwords are case-sensitive) and that the user has CONNECT and SELECT privileges. More.
"ORA-12514: TNS:listener does not currently know of service requested"
The service name is wrong. Look it up with SELECT VALUE FROM V$PARAMETER WHERE NAME = 'service_names'. More.
"ORA-12541: TNS:no listener"
The Oracle listener isn't running on that host and port (1521 by default). More.
Oracle "connection refused"
Oracle isn't running, the port is wrong, or a firewall blocks it. More.
Snowflake
"390100: Missing account identifier"
The DSN has no account identifier. Use user:pass@ACCOUNT/DB/SCHEMA?warehouse=WH, or --account. More.
"390144: Role does not exist or not authorized"
The role doesn't exist or isn't granted to the user. Check SHOW GRANTS TO USER your_user. More.
"No active warehouse"
Add warehouse=COMPUTE_WH (or --warehouse), or give the user a default warehouse. More.
Slow first Snowflake query
The warehouse was suspended and is resuming. Raise AUTO_SUSPEND to reduce this. More.
SQLite
"database is locked"
SQLite allows one writer at a time. Enable WAL mode (_journal_mode=WAL), raise the busy timeout, or set max_open_conns to 1. More.
"no such table"
The table isn't in that file. Check with sqlite3 /path/to/db.sqlite ".tables". More.
"unable to open database file"
The path doesn't exist or Faucet can't read or write it. Use an absolute path and check permissions. More.
Foreign keys not enforced
SQLite disables them by default. Add _foreign_keys=on to the DSN. More.
API keys, roles and MCP
401 Unauthorized
The request has no valid credentials. Send X-API-Key: faucet_... (or an admin Authorization: Bearer token) with every /api/v1/{service} and /mcp request. See API Reference → Authentication.
403 Forbidden with an API key
The key's role has no rule that allows this service, table and verb. A role created without --verbs denies everything. Add a rule with faucet role grant --role <name> --verbs GET or in the admin UI. See RBAC and faucet role grant.
An MCP client cannot connect
Send the initialize request with curl. A reply containing serverInfo means the URL and key work, so the problem is in the client config. See Test the endpoint with curl.
Claude Desktop cannot reach a remote Faucet over http://
mcp-remote refuses plain HTTP to another machine unless you add "--allow-http" to its args. Prefer HTTPS. See Connect Claude Desktop.
ChatGPT asks for OAuth
ChatGPT connectors need OAuth, which Faucet does not offer yet. Use a Custom GPT Action that imports /openapi.json with the X-API-Key header. See Use Faucet from ChatGPT.
Admin UI
The admin UI is blank or "not available"
The binary was built without the UI. Release binaries, Docker images and the npm package include it; from source, build ui/ before make build. More.
Locked out of the admin UI
Create another admin on the server with faucet admin create --email [email protected].
Still stuck?
Open an issue on GitHub with the error message, your Faucet version (faucet version) and database type, or email [email protected].