# Troubleshooting Source: https://wiki.faucetdb.ai/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](https://wiki.faucetdb.ai/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](https://wiki.faucetdb.ai/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](https://wiki.faucetdb.ai/admin-ui#troubleshooting). ### 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](https://wiki.faucetdb.ai/tutorial-oracle#password-with-special-characters). ## PostgreSQL ### "password authentication failed" Wrong username or password, or `pg_hba.conf` requires a different auth method for your host. [More](https://wiki.faucetdb.ai/tutorial-postgres#password-authentication-failed). ### "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](https://wiki.faucetdb.ai/tutorial-postgres#no-pg-hba-conf-entry-for-host). ### "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](https://wiki.faucetdb.ai/tutorial-postgres#ssl-is-not-enabled-on-the-server). ### "relation does not exist" The table isn't in the schema Faucet is using. Check `search_path` or `--schema`. [More](https://wiki.faucetdb.ai/tutorial-postgres#relation-does-not-exist). ## 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](https://wiki.faucetdb.ai/tutorial-mysql#access-denied-for-user). ### "Unknown database" The database in the connection doesn't exist. Create it with `CREATE DATABASE`. [More](https://wiki.faucetdb.ai/tutorial-mysql#unknown-database). ### "dial tcp: connect: connection refused" Nothing is listening on that host and port, or a firewall blocks it. [More](https://wiki.faucetdb.ai/tutorial-mysql#dial-tcp-connect-connection-refused). ### Timestamps look wrong Add `loc=UTC` or `loc=Local` to the DSN, and keep `parseTime=true`. [More](https://wiki.faucetdb.ai/tutorial-mysql#timezone-issues). ## SQL Server ### "Login failed for user" Wrong username or password; for `sa`, the password must meet SQL Server's complexity rules. [More](https://wiki.faucetdb.ai/tutorial-sqlserver#login-failed-for-user). ### "Cannot open server requested by the login" The database named in the connection doesn't exist. [More](https://wiki.faucetdb.ai/tutorial-sqlserver#cannot-open-server-requested-by-the-login). ### "TLS Handshake failed" Use `encrypt=disable` for local development or `TrustServerCertificate=true` for a self-signed certificate; use a proper certificate in production. [More](https://wiki.faucetdb.ai/tutorial-sqlserver#tls-handshake-failed). ### SQL Server "connection refused" SQL Server isn't running, the port is wrong, or TCP/IP is disabled in SQL Server Configuration Manager. [More](https://wiki.faucetdb.ai/tutorial-sqlserver#connection-refused). ## Oracle ### "ORA-01017: invalid username/password" Check the credentials (Oracle passwords are case-sensitive) and that the user has `CONNECT` and `SELECT` privileges. [More](https://wiki.faucetdb.ai/tutorial-oracle#ora-01017-invalid-username-password). ### "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](https://wiki.faucetdb.ai/tutorial-oracle#ora-12514-tns-listener-does-not-currently-know-of-service-requested). ### "ORA-12541: TNS:no listener" The Oracle listener isn't running on that host and port (1521 by default). [More](https://wiki.faucetdb.ai/tutorial-oracle#ora-12541-tns-no-listener). ### Oracle "connection refused" Oracle isn't running, the port is wrong, or a firewall blocks it. [More](https://wiki.faucetdb.ai/tutorial-oracle#connection-refused). ## Snowflake ### "390100: Missing account identifier" The DSN has no account identifier. Use `user:pass@ACCOUNT/DB/SCHEMA?warehouse=WH`, or `--account`. [More](https://wiki.faucetdb.ai/tutorial-snowflake#_390100-missing-account-identifier). ### "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](https://wiki.faucetdb.ai/tutorial-snowflake#_390144-role-does-not-exist-or-not-authorized). ### "No active warehouse" Add `warehouse=COMPUTE_WH` (or `--warehouse`), or give the user a default warehouse. [More](https://wiki.faucetdb.ai/tutorial-snowflake#no-active-warehouse). ### Slow first Snowflake query The warehouse was suspended and is resuming. Raise `AUTO_SUSPEND` to reduce this. [More](https://wiki.faucetdb.ai/tutorial-snowflake#slow-first-query). ## 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](https://wiki.faucetdb.ai/tutorial-sqlite#database-is-locked). ### "no such table" The table isn't in that file. Check with `sqlite3 /path/to/db.sqlite ".tables"`. [More](https://wiki.faucetdb.ai/tutorial-sqlite#no-such-table). ### "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](https://wiki.faucetdb.ai/tutorial-sqlite#unable-to-open-database-file). ### Foreign keys not enforced SQLite disables them by default. Add `_foreign_keys=on` to the DSN. [More](https://wiki.faucetdb.ai/tutorial-sqlite#foreign-keys-not-enforced). ## 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](https://wiki.faucetdb.ai/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 --verbs GET` or in the admin UI. See [RBAC](https://wiki.faucetdb.ai/rbac) and [`faucet role grant`](https://wiki.faucetdb.ai/cli-reference#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](https://wiki.faucetdb.ai/mcp-server#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](https://wiki.faucetdb.ai/mcp-server#connect-claude-desktop-via-mcp-remote). ### 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](https://wiki.faucetdb.ai/mcp-server#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](https://wiki.faucetdb.ai/admin-ui#troubleshooting). ### Locked out of the admin UI Create another admin on the server with `faucet admin create --email you@example.com`. ## Still stuck? Open an issue on [GitHub](https://github.com/faucetdb/faucet/issues) with the error message, your Faucet version (`faucet version`) and database type, or email [developers@faucetdb.ai](mailto:developers@faucetdb.ai).