1. Docs
  2. Resources
  3. Data Source
  4. Troubleshooting

Troubleshooting

Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it.

11 min read Updated CustomersAdmins

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

  1. Copy the first words of the message you see.
  2. Find the entry with the same words below.
  3. Work through Check, then apply Fix.
  4. 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 of SELECT * 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 _TEST or _PRP makes an environment variant.
“The dataset could not be saved”Datasets
Check
  1. The dataset has a Name; Save does nothing without one.
  2. Your session is still valid: refresh the page in another tab.
  3. 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
  1. User name and password, without spaces.
  2. For a saved connection, an empty password field means the stored password is used. Type it again if it may be outdated.
  3. 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
  1. Host and port in the Database Url.
  2. The host is a public name, not localhost or a private address.
  3. 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.Driver or com.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 example jdbc: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=require for 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
  1. Bootstrap Servers as host:port, comma-separated.
  2. Security Protocol matches the broker port (SSL ports need SSL or SASL_SSL).
  3. For a saved SASL connection, type the SASL Password again: the test uses only the form.
  4. The brokers accept connections from SmartestQA.
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
  1. Where the run ran (Run on Server or Run on your Agent).
  2. From that machine, the database host and port are reachable.
  3. The Database Url starts with jdbc:postgresql, jdbc:mysql or jdbc: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
  1. Run the query in your database tool with the connection’s user.
  2. The data exists in the environment the run used.
  3. 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
  1. The suffix is upper case and at the very end: apiBase_TEST, not apiBase_test or apiBase_TEST1.
  2. The step references the name without suffix: {{ds:apiBase}}.
  3. The run really used TEST. Send previews always use the default value.
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 user are 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
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smarttest-fe predev 2a8c79cc, smarttest-be 633c2a03, smarttest-testsuite (runner)