- Docs
- Resources
- Data Source
- Troubleshooting
Troubleshooting
Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it.
In short
On this page you can
- Look up a Data Source message and see why it appears.
- Fix Test Connection failures by their exact reason.
- Find out why a run cannot reach a database that tests fine.
- Fix keys and dataset columns that do not resolve in a run.
How to use it
- Copy the first words of the message you see.
- Find the entry with the same words below.
- Work through Check, then apply Fix.
- Still stuck: send the message and the run link to info@smartestqa.ai.
Keys#
“This key already exists. Please enter a different name.”Keys
- Why
- Key names are unique in the project, across all folders.
- Check
- Search the key list for the name. It may sit in a collapsed folder.
- Fix
- Pick another name, or use the existing key. For a value per environment, add the suffix:
apiBase_TEST(see Environment-specific keys).
“Key field cannot be empty. Please enter a key.”Keys
- Why
- A key needs a name; steps reference it by that name.
- Fix
- Type a name in Key. Spaces are removed automatically.
“Error creating Data Source” / “Error updating data source.”Keys
- Why
- The server rejected the save, for example because your session expired, the folder was deleted in another tab, or the DB connection used by the key was removed.
- Fix
- Refresh the page (F5), open the key again and save. If a DB binding is involved, pick the connection again in DB query.
“Failed to delete data source. Please try again.” / I can’t delete a keyKeys
- Why
- Deleting a key, or a folder that still has keys or sub folders, needs an Admin.
- Check
- Your role in Roles & permissions.
- Fix
- Ask an Admin to delete it. Before that, find the tests that use
{{ds:key}}: they lose their value. See Delete.
“This datasource is associated with a DB object. Copy cannot be performed.” / “Copy Error”Keys
- Why
- A key whose value comes from a DB query cannot be copied. “Copy Error” means the copy failed on the server.
- Fix
- Create a new key and set its DB query by hand. For “Copy Error”, refresh and try again.
“Error updating folder: …” / “Failed to save folder.” / “Failed to delete folder.”Folders
- Why
- A rename or move of a key folder, or a save or delete of a dataset or connection folder, was rejected. The text after “Error updating folder:” is the server’s reason.
- Fix
- Refresh and try again. A folder cannot be moved into its own sub folder, and the top level cannot be deleted.
The eye icon to show an encrypted value is missingSecrets
- Why
- Only the person who created an encrypted value can show it. Admins cannot either.
- Fix
- Ask the creator (see Created by), or type a new value and save. See Who can see an encrypted value.
My key lost its value after I switched Encrypt offSecrets
- Why
- The old secret is never sent to the screen, so the field was empty when you saved.
- Fix
- Type the value again and save. Next time, type the new plain value before you save. See Replace or remove a secret.
DB and dataset bindings#
“This data source is bound to a DB. Remove the DB binding first to link a dataset.” / “…linked to a dataset. Remove the dataset link first to bind a DB.”Bindings
- Why
- A key has one value source at a time.
- Fix
- Switch Value comes from to Typed value, save, then choose the other source. Or remove the binding in its dialog with Remove. See One source at a time.
“Configuration not selected”Bindings
- Why
- The DB Request dialog needs a DB connection.
- Fix
- Choose one in Configuration. If the list is empty, add a DB connection first.
“Empty query.” / 'Query must be in "SELECT ... FROM ..." format.' / “Asterisk (*) is not allowed…”SQL
- Why
- A SELECT must list explicit columns. The same rules give “SELECT clause must contain at least one column.” and “Specify at least one column (you can use aliases).”
- Fix
- Write
SELECT order_no FROM orders WHERE …instead ofSELECT * FROM orders. Quote uppercase or reserved names:"user".
“This query makes permanent changes in the database (committed)…” / “No WHERE clause detected…” / “Caution: This operation (DROP/TRUNCATE)…”SQL
- Why
- These are warnings, not errors. The statement changes data, has no WHERE, drops or truncates, or (“A stored procedure / routine call will be executed.”) calls a procedure. You can still save.
- Fix
- Make sure it is meant. For a key, prefer a SELECT: the query runs every time a step reads the key.
Datasets#
“This name already exists in this project. Please enter a different name.”Names
- Why
- Dataset names, DB connection names and Kafka connection names are each unique in the project. The comparison is case-sensitive.
- Fix
- Choose another name, for example with the environment:
Orders DB (TEST). For datasets, the suffix_TESTor_PRPmakes an environment variant.
“The dataset could not be saved”Datasets
- Check
-
- The dataset has a Name; Save does nothing without one.
- Your session is still valid: refresh the page in another tab.
- The file is a real XLSX, XLS or CSV, and the data is on the first sheet.
- Fix
- Fix the cause and save again. “Please fill in the required fields.” means a required field is empty.
“The dataset could not be deleted” / “Please select a dataset to delete.”Datasets
- Why
- The server refused the delete, for example because keys still read a cell of the dataset. “Please select a dataset to delete.” appears when no saved dataset is open; “Project not found. Please refresh the page.” when the project is missing.
- Check
- The Used by column (hover it for the key names).
- Fix
- Switch those keys to another source, save them, then delete the dataset.
“The selected dataset is empty” / “Dataset data not available”Datasets
- Why
- The dataset you opened to pick a cell has no rows.
- Fix
- Open it under Datasets, add rows with Add row or Replace from file, and save.
A step types {{excel:users}}_email literallyDatasets
- Why
- The dataset name or the column name does not match. Headers are turned into camelCase names on upload: “Login Email” becomes
loginEmail. - Check
- The Columns cell of the dataset in the list, and its exact name.
- Fix
- Use the stored names:
{{excel:users}}_loginEmail. See How column names are made.
Connections#
“Connection test failed.” / “Error testing connection.”Test Connection
- Why
- For a database, the message usually names the reason (entries below) and shows the driver’s own text underneath, shortened to 300 characters, with the password masked. The plain “Connection test failed.” means the reason is not one of those. “Error testing connection.” means the test itself could not be started.
- Check
- Read the driver text under the message. It often names the exact problem.
- Fix
- Fix the cause, click Test Connection again. Remember the test runs from the SmartestQA server; see Where connections are opened from.
“Connection test failed: the username or password is wrong, or this user may not connect to the database.”Test Connection
- Check
- User name and password, without spaces.
- For a saved connection, an empty password field means the stored password is used. Type it again if it may be outdated.
- The user may log in from outside (for PostgreSQL, the server’s access rules).
- Fix
- Correct the login and save. If the database requires an allow list per user and host, ask your DBA.
“Connection test failed: the database server could not be reached…”Test Connection
- Why
- Wrong host or port, or a firewall that does not accept connections from SmartestQA.
- Check
- Host and port in the Database Url.
- The host is a public name, not
localhostor a private address. - The firewall or IP allow list admits SmartestQA.
- Fix
- Correct the URL or open the firewall. If the database must stay private, run tests on an agent inside your network and verify with a Dry Run there.
“Connection test failed: the database named in the URL was not found on the server.”Test Connection
- Fix
- Correct the database name after the port (
…:5432/shop). Names can be case-sensitive.
“Connection test failed: the DB Driver Class could not be loaded…”Test Connection
- Check
- The class name exactly, for example
org.postgresql.Driverorcom.mysql.cj.jdbc.Driver. See URL and driver examples. - Fix
- Correct the class name. If it is right and the error stays, the SmartestQA server may not have that driver: write to info@smartestqa.ai with the database type.
“Connection test failed: the Database Url is not valid for this driver. It must start with jdbc:…”Test Connection
- Fix
- Start the URL with
jdbc:and the database type, for examplejdbc:postgresql://host:5432/db. The driver class must match the type.
“Connection test failed: the database server did not answer in time.”Test Connection
- Why
- Usually a firewall that drops packets instead of refusing them, or an overloaded server.
- Fix
- Treat it like server could not be reached, then try again.
“Connection test failed: secure (SSL/TLS) connection error…”Test Connection
- Fix
- Add or correct the SSL settings in the URL as your driver expects, for example
?sslmode=requirefor PostgreSQL. Ask your DBA whether the server needs SSL.
Kafka: “Connection test failed.”Kafka
- Why
- The brokers did not describe the cluster within 5 seconds. Kafka tests give no reason.
- Check
- Bootstrap Servers as
host:port, comma-separated. - Security Protocol matches the broker port (SSL ports need
SSLorSASL_SSL). - For a saved SASL connection, type the SASL Password again: the test uses only the form.
- The brokers accept connections from SmartestQA.
- Bootstrap Servers as
- Fix
- Correct the settings and test again. See Add a Kafka connection.
“DB Name is required” / “Database URL is required.” / “Bootstrap servers is required.” / “Please fill in the required fields.”Connections
- Why
- A required field is empty. Also “DB driver class is required.”, “Name is required.” and, for SASL protocols, “SASL mechanism is required when a SASL_* protocol is selected.” and “SASL username is required when a SASL_* protocol is selected.”
- Fix
- Fill every field labelled “(Required)”.
“Password is required for a new connection.” / “SASL password is required when a SASL_* protocol is selected.”Connections
- Why
- A new connection must have a password. When you edit a saved one, an empty field keeps the stored password.
- Fix
- Type the password. For a login without a password, ask your DBA for a test user with one: it is safer and SmartestQA expects it.
“Error saving DB configuration.” / “Error saving Kafka configuration.” / “Error deleting DB configuration.” / “Error deleting Kafka configuration.”Connections
- Why
- The server rejected the change. “No DB configuration selected to delete.” and “No Kafka configuration selected.” mean no saved connection is open.
- Fix
- Refresh the page, open the connection from its list and try again. For a DB connection that tests use, see Delete a database connection.
In runs#
Test Connection works, but the run cannot connect (or the other way round)Runs
- Why
- Test Connection connects from the SmartestQA server. A run connects from the machine that runs it: the server, your agent, a self-hosted runner, or AWS Device Farm. See Where connections are opened from.
- Check
- Where the run ran (Run on Server or Run on your Agent).
- From that machine, the database host and port are reachable.
- The Database Url starts with
jdbc:postgresql,jdbc:mysqlorjdbc:oracle: the run reads the database type from it.
- Fix
- Run on a machine that can reach the database (Do you need an agent?), or open the firewall for the runner.
“Could not resolve DB data source 'key': …”Runs
- Why
- The key’s SQL query failed or returned no rows (“query returned no rows (0)”). The step fails; it never uses an old value.
- Check
- Run the query in your database tool with the connection’s user.
- The data exists in the environment the run used.
- The run’s machine can reach the database (above).
- Fix
- Correct the query or create the data first in an earlier step. See Read a value from a database.
“Could not resolve Excel data source 'key': …”Runs
- Why
- The key is linked to a dataset cell that cannot be read. The reason follows the colon: “excel has no rows”, “row N not found”, “column 'x' not found”, “invalid cell reference”.
- Fix
- Open the dataset and check the row and column, or link the key to the cell again.
A step uses {{ds:…}} literally, or gets an empty valueRuns
- Why
- No key has that name (typo, renamed or deleted key), or the key exists but has no value (it is in the No value card).
- Check
- The exact name in Variables, including upper and lower case.
- Fix
- Correct the reference with the picker, or fill the key. After a rename, update the steps. See What happens at run time.
The run ignores my _TEST keyRuns
- Check
- The suffix is upper case and at the very end:
apiBase_TEST, notapiBase_testorapiBase_TEST1. - The step references the name without suffix:
{{ds:apiBase}}. - The run really used TEST. Send previews always use the default value.
- The suffix is upper case and at the very end:
- Fix
- Rename the key or the reference. See Environment-specific keys.
“No Kafka configuration found. Create one on the Data Source page (Kafka tab).”Kafka
- Why
- The project has no Kafka connection. Kafka connections are in the Connections tab of Data Source.
- Fix
- Add a Kafka connection, then reopen the Kafka step.
“Configuration not found” / “Configuration must be selected.” in a DB stepDB steps
- Why
- The project has no DB connection, or none is selected. The DB step also asks for its query and outputs: “SQL query cannot be empty.”, “Output values cannot be empty.”
- Fix
- Add a DB connection, choose it, and fill the query and Output Values. See DB steps.
'The column "…" was not found in the table…' / 'The table "…" was not found…'DB steps
- Why
- Names are case-sensitive in many databases, and words like
userare reserved. - Fix
- Use the exact names and double quotes:
SELECT "Email" FROM "user". For “SQL syntax error. Review the query near the marked position (^).”, run the query in your database tool first.
“Could not connect to the database…” / “Database authentication failed…” / “The JDBC driver could not be loaded…”DB steps
- Why
- The machine that runs the test could not log in to the database.
- Fix
- Same checks as Test Connection works, the run cannot connect and wrong username or password.
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai