---
title: "Troubleshooting"
section: "Data Source"
description: "Fixes for SmartestQA Data Source: keys, DB and dataset bindings, datasets, Test Connection failures, Kafka, and values that do not resolve in a run."
url: https://docs.smartestqa.ai/en/data-source-troubleshooting.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "data source error connection test failed username password host unreachable driver url timeout ssl key already exists could not resolve db data source excel dataset kafka"
---
# Data Source: 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**

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

### Problem: “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](https://docs.smartestqa.ai/en/data-source-variables.html#find-keys) 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](https://docs.smartestqa.ai/en/data-source-variables.html#environments)).

### Problem: “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.

### Problem: “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](https://docs.smartestqa.ai/en/data-source-variables.html#bind-db-query).

### Problem: “Failed to delete data source. Please try again.” / I can’t delete a key _(Keys)_

- **Why:** Deleting a key, or a folder that still has keys or sub folders, needs an Admin.
- **Check:** Your role in [Roles & permissions](https://docs.smartestqa.ai/en/company-settings-roles.html).
- **Fix:** Ask an Admin to delete it. Before that, find the tests that use `{{ds:key}}`: they lose their value. See [Delete](https://docs.smartestqa.ai/en/data-source-variables.html#delete).

### Problem: “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](https://docs.smartestqa.ai/en/data-source-variables.html#bind-db-query) by hand. For “Copy Error”, refresh and try again.

### Problem: “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.

### Problem: The eye icon to show an encrypted value is missing _(Secrets)_

- **Why:** Only the person who created an encrypted value can show it. [Admins](https://docs.smartestqa.ai/en/company-settings-roles.html) cannot either.
- **Fix:** Ask the creator (see **Created by**), or type a new value and save. See [Who can see an encrypted value](https://docs.smartestqa.ai/en/data-source-secrets.html#who-sees-what).

### Problem: My key lost its value after I switched Encrypt off _(Secrets)_

- **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](https://docs.smartestqa.ai/en/data-source-secrets.html#replace).

## DB and dataset bindings

### Problem: “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**](https://docs.smartestqa.ai/en/data-source-variables.html#value-source) to [**Typed value**](https://docs.smartestqa.ai/en/data-source-variables.html#value-source), save, then choose the other source. Or remove the binding in its dialog with **Remove**. See [One source at a time](https://docs.smartestqa.ai/en/data-source-variables.html#one-source).

### Problem: “Configuration not selected” _(Bindings)_

- **Why:** The [**DB Request**](https://docs.smartestqa.ai/en/data-source-variables.html#bind-db-query) dialog needs a DB connection.
- **Fix:** Choose one in **Configuration**. If the list is empty, [add a DB connection](https://docs.smartestqa.ai/en/data-source-connections.html#add-db) first.

### Problem: “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"`.

### Problem: “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

### Problem: “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](https://docs.smartestqa.ai/en/data-source-datasets.html#dataset-environments).

### Problem: “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.

### Problem: “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.

### Problem: “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**](https://docs.smartestqa.ai/en/data-source-datasets.html), add rows with **Add row** or [**Replace from file**](https://docs.smartestqa.ai/en/data-source-datasets.html#edit), and save.

### Problem: A step types `{{excel:users}}_email` literally _(Datasets)_

- **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](https://docs.smartestqa.ai/en/data-source-datasets.html#column-names).

## Connections

### Problem: “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](https://docs.smartestqa.ai/en/data-source-in-tests.html#where-it-connects).

### Problem: “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.

### Problem: “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**](https://docs.smartestqa.ai/en/data-source-connections.html#add-db).
  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](https://docs.smartestqa.ai/en/agent-pool-agents.html) inside your network and verify with a [Dry Run](https://docs.smartestqa.ai/en/automate-dry-run.html) there.

### Problem: “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.

### Problem: “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](https://docs.smartestqa.ai/en/data-source-connections.html#db-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.

### Problem: “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.

### Problem: “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](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-conn-host), then try again.

### Problem: “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.

### Problem: 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**](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka) as `host:port`, comma-separated.
  2. [**Security Protocol**](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka) matches the broker port (SSL ports need `SSL` or `SASL_SSL`).
  3. For a saved SASL connection, type the [**SASL Password**](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka) 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](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka).

### Problem: “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)”.

### Problem: “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.

### Problem: “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](https://docs.smartestqa.ai/en/data-source-connections.html#delete-db).

## In runs

### Problem: 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](https://docs.smartestqa.ai/en/agent-pool-agents.html), a self-hosted runner, or [AWS Device Farm](https://docs.smartestqa.ai/en/project-settings-mobile.html#aws). See [Where connections are opened from](https://docs.smartestqa.ai/en/data-source-in-tests.html#where-it-connects).
- **Check:** 1. Where the run ran ([**Run on Server**](https://docs.smartestqa.ai/en/quick-start-connect.html#agent) or [**Run on your Agent**](https://docs.smartestqa.ai/en/quick-start-connect.html#agent)).
  2. From that machine, the database host and port are reachable.
  3. The [**Database Url**](https://docs.smartestqa.ai/en/data-source-connections.html#add-db) 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?](https://docs.smartestqa.ai/en/quick-start-connect.html#agent)), or open the firewall for the runner.

### Problem: “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](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-works-in-test-fails-in-run)).
- **Fix:** Correct the query or create the data first in an earlier step. See [Read a value from a database](https://docs.smartestqa.ai/en/data-source-variables.html#bind-db-query).

### Problem: “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](https://docs.smartestqa.ai/en/data-source-variables.html#bind-dataset-cell).

### Problem: A step uses `{{ds:…}}` literally, or gets an empty value _(Runs)_

- **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](https://docs.smartestqa.ai/en/data-source-in-tests.html#at-run-time).

### Problem: The run ignores my `_TEST` key _(Runs)_

- **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](https://docs.smartestqa.ai/en/data-source-variables.html#environments).

### Problem: “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](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka), then reopen the [Kafka step](https://docs.smartestqa.ai/en/automate-steps-kafka.html).

### Problem: “Configuration not found” / “Configuration must be selected.” in a DB step _(DB 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](https://docs.smartestqa.ai/en/data-source-connections.html#add-db), choose it, and fill the query and [**Output Values**](https://docs.smartestqa.ai/en/automate-steps-database.html#outputs). See [DB steps](https://docs.smartestqa.ai/en/data-source-in-tests.html#db-steps).

### Problem: '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.

### Problem: “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](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-works-in-test-fails-in-run) and [wrong username or password](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-conn-auth).
