---
title: "Step troubleshooting"
section: "Step reference"
description: "Fixes for SmartestQA step problems: element steps, assertions, variables and code, API, database, mail, Kafka, Network, AI, load tests, mobile and desktop."
url: https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "step error element not found timeout stale type appends assertion failed variable not resolved api 404 passes json path sql error mail timeout otp kafka timeout network no matching request ai step disabled jmeter not found"
---
# Step reference: Step troubleshooting

Find the message or the behaviour you see. Each entry says why it happens, what to check and how to fix it. Messages are quoted as they appear in the editor, the live log or the report.

## In short

**On this page you can**

- Find the exact step message you see in the live log or the report.
- Learn why a step failed, errored or passed when it should not.
- Fix element, variable, API, database, mail, Kafka and Network problems.
- Fix AI, load-test, mobile and desktop step problems.
- Jump to the family page that explains the step in full.

**How to use it**

1. Open the failed run: the live log of the Dry Run, or the report of the pipeline run.
2. Read the failed step’s message and the reason after the colon.
3. Search this page for the message, or open the section of the step type.
4. Apply the fix, save the test case, and run a Dry Run again.
5. If the message is not here, write to info@smartestqa.ai with the run link.

## Element steps

### Problem: “Failed to click on "…": Element not found | Locator: …” (or Timeout, not clickable, stale) _(Element)_

- **Why:** No locator of the action matched within the time, after [3 attempts](https://docs.smartestqa.ai/en/automate-steps-flow.html#timeouts) and auto-heal. The reason after the colon tells which: “Element not found”, “Element not clickable” (something covers it), “Element not interactable” (hidden or disabled), “Timeout — element did not become ready in time”, “Element is no longer valid on the page (stale)”, “Frame not found”, “Invalid selector”, “Browser window/tab is not available”.
- **Check:** 1. The [screenshot of the step](https://docs.smartestqa.ai/en/report-steps.html#screenshots): is the page the one you expect, or a login, error or loading page?
  2. The locator after `Locator:`: does it still match the element in the app?
  3. Did an earlier click open a new tab ([Selenium stays on the old one](https://docs.smartestqa.ai/en/automate-steps-browser.html#engines))?
- **Fix:** Fix or add a locator in [Action Detail](https://docs.smartestqa.ai/en/discover-actions.html#manual-action), preferring `id` or `data-testid`. Add a wait for slow pages ([Waits](https://docs.smartestqa.ai/en/automate-steps-flow.html#waits)). For a new tab in Selenium, switch tabs in a [Python step](https://docs.smartestqa.ai/en/automate-steps-code.html). [Auto-heal](https://docs.smartestqa.ai/en/maintenance-how-healing-works.html#when) does not run on login pages or when the app returns 401, 403 or 5xx.

### Problem: Type added the text after the old value _(Element)_

- **Why:** [Type](https://docs.smartestqa.ai/en/automate-steps-browser.html#type) does not clear the field; it appends.
- **Fix:** Use a **Clear & Type** action for that field: [replace the step’s action](https://docs.smartestqa.ai/en/automate-editor.html#replace-action) with one of type Clear & Type and enter the value again. Changing the type of the [shared action](https://docs.smartestqa.ai/en/discover-actions.html#change-and-delete) itself changes every test case that uses it.

### Problem: “Failed to select option from "…"” _(Element)_

- **Why:** [Select](https://docs.smartestqa.ai/en/automate-steps-browser.html#select) matches the option’s visible text exactly, and works on real dropdown elements.
- **Fix:** Copy the option text from the page (case, spaces). For dropdowns built from other elements, use a [Click](https://docs.smartestqa.ai/en/automate-steps-browser.html#click) to open it and a Click on the option.

### Problem: The test went on after a failed Visibility Check _(Checks)_

- **Why:** A failed [Visibility Check](https://docs.smartestqa.ai/en/automate-steps-browser.html#visibility-check) marks the step FAILED but does not stop the test case.
- **Fix:** Where the flow must stop, read the value with [Get](https://docs.smartestqa.ai/en/automate-steps-browser.html#get) and use an [Assertion](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-step), which stops the case.

### Problem: “Text or locator is required for visibility check.” _(Checks)_

- **Fix:** Give the step an [action with a locator](https://docs.smartestqa.ai/en/discover-actions.html), or an expected text value, or both.

### Problem: Wait step: “no wait time given…”, “… is not a valid number of seconds”, “… is out of the allowed range (0.1 - 3600 s)” _(Wait)_

- **Why:** The value of [Wait (seconds)](https://docs.smartestqa.ai/en/automate-steps-browser.html#wait-seconds) is empty, not a number, outside 0.1–3600, or a variable that could not be resolved.
- **Fix:** Enter a number such as `2` or `0.5` (dot as decimal mark). If it is a [variable](https://docs.smartestqa.ai/en/automate-steps-variables.html#pass-values), make sure the step that sets it runs first.

## Checks

### Problem: “No assertion type is selected for this step…” / “Unsupported assertion type: '…'” _(Assertion)_

- **Fix:** Select the step and pick a type from the assertion type list in the right panel, for example Equals. See [Assertion types](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-types).

### Problem: “Expected is empty — enter the text to look for with '…'” / “'expected' value was not found…” _(Assertion)_

- **Why:** Contains, Starts With and similar types need an expected value.
- **Fix:** Fill **expected**, or switch to [Is Empty / Is Not Empty](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-types) if you only check presence.

### Problem: “Actual is not a number: '…'” / “Expected is not a number: '…'” _(Assertion)_

- **Why:** Greater Than and Less Than compare numbers. A value such as `€ 1.234,50` or `12 items` is text.
- **Fix:** Add the **To Number** transform to the [Get step](https://docs.smartestqa.ai/en/automate-steps-browser.html#get) that reads it. See [Transforms](https://docs.smartestqa.ai/en/automate-steps-variables.html#transforms).

### Problem: An assertion fails although the values look the same _(Assertion)_

- **Why:** Text comparison is case-sensitive and does not trim spaces or line breaks.
- **Fix:** Use Contains, or clean the value with [Trim / Lower Case transforms](https://docs.smartestqa.ai/en/automate-steps-variables.html#transforms). See [Comparison rules](https://docs.smartestqa.ai/en/automate-steps-assertions.html#comparison-rules).

## Variables and code

### Problem: A step typed `{{tc:name}}` instead of the value, or the log says “… not found, treated as empty” _(Variables)_

- **Why:** The reference could not be resolved: the name is spelled differently, the producing step did not run ([inactive](https://docs.smartestqa.ai/en/automate-steps-flow.html#inactive-steps), [skipped branch](https://docs.smartestqa.ai/en/automate-steps-flow.html#if-else), failed), or it runs after this step.
- **Check:** The exact output name of the [producing step](https://docs.smartestqa.ai/en/automate-steps-variables.html#producers) (case matters) and its position in the list.
- **Fix:** Use the [picker icon](https://docs.smartestqa.ai/en/automate-test-data.html#insert-variable) to insert the reference instead of typing it. See [Reference syntax](https://docs.smartestqa.ai/en/automate-steps-variables.html#syntax).

### Problem: “Parameter key can only contain letters, digits and underscore” _(Variables)_

- **Fix:** Rename the [Get](https://docs.smartestqa.ai/en/automate-steps-browser.html#get) or [Global parameter](https://docs.smartestqa.ai/en/automate-steps-variables.html#global-parameter) key: `order_id`, not `order-id` or `order id`.

### Problem: “This key is already registered as a global parameter, please change the key value.: …” / “Names that produce a global parameter must be unique within the test case. Conflicts: …” _(Variables)_

- **Fix:** Give each output a unique name within the test case, and do not reuse a name that another source [already registered](https://docs.smartestqa.ai/en/automate-test-data.html#produce-variables). See [Steps that produce variables](https://docs.smartestqa.ai/en/automate-steps-variables.html#producers).

### Problem: “Code body cannot be empty” / “… code is empty for Python step(s): … Dry Run was not started.” _(Code)_

- **Why:** A Python or JavaScript step has no code, or in a web project the Python step has code only in the tab of the other engine (Selenium or Playwright).
- **Fix:** Write the code in the tab of the [engine the project uses](https://docs.smartestqa.ai/en/project-settings-test-management.html#engine), or remove the step. See [Python or JavaScript](https://docs.smartestqa.ai/en/automate-steps-code.html#compare).

### Problem: The STATUS check failed (“… STATUS check failed … Returned value: …”) _(Code)_

- **Why:** In **Status** mode the code produced a false value, or nothing.
- **Fix:** Return `true` or `false` explicitly. If the step should only act, set the output to **N/A**. See [Output modes](https://docs.smartestqa.ai/en/automate-steps-code.html#output-modes).

### Problem: “The test could not start — a step's code or IF/ELSE/END structure is invalid…” _(Code)_

- **Why:** An IF has no END, an ELSE has no IF, an IF or ELIF condition is empty, or a Python step does not compile. The run stops before the first step.
- **Fix:** Check that every IF block ends with an END step and that each condition is a valid Python expression. See [Conditions](https://docs.smartestqa.ai/en/automate-steps-flow.html#if-else).

### Problem: “[IF] Condition could not be evaluated” _(Code)_

- **Why:** The condition raised an error, typically comparing text with a number.
- **Fix:** [Wrap numbers](https://docs.smartestqa.ai/en/automate-steps-flow.html#if-else): `int({{tc:count}}) > 10`; quote text: `"{{tc:status}}" == "PAID"`.

### Problem: “Project type could not be read - the code cannot be edited. Reload the page.” _(Code)_

- **Fix:** Reload the page. The editor needs the project type to know the code format (web or mobile/desktop).

## API

### Problem: The API step passed although the API returned 404 or 500 _(API)_

- **Why:** Any HTTP answer counts as a successful step; even a timeout lets the case continue.
- **Fix:** Save `@status` into a variable and add an [Assertion](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-step). See [Check the status code](https://docs.smartestqa.ai/en/automate-steps-api.html#check-the-status).

### Problem: “Unsupported HTTP method: HEAD” (or OPTIONS) at run time _(API)_

- **Why:** The [editor](https://docs.smartestqa.ai/en/api-requests-editor.html#request-line) accepts HEAD and OPTIONS, but the runner sends only GET, POST, PUT, PATCH and DELETE.
- **Fix:** Use GET instead, or call the endpoint from a [Python step](https://docs.smartestqa.ai/en/automate-steps-code.html).

### Problem: Send: “The request timed out (30s)…”, “Host not found…”, “Connection refused…” _(API)_

- **Why:** **Send** runs from the SmartestQA server, which [cannot reach internal or local addresses](https://docs.smartestqa.ai/en/company-settings-network.html#egress).
- **Fix:** Add JSON paths by hand (plus icon) and test the step with a [Dry Run](https://docs.smartestqa.ai/en/automate-dry-run.html#start-dry-run) on [your agent](https://docs.smartestqa.ai/en/agent-pool-agents.html). See [Send](https://docs.smartestqa.ai/en/automate-steps-api.html#send).

### Problem: “Fill in the key and the JSON path, or remove this row” / “JSON path is invalid and cannot work at runtime” / “No match in the response” _(API)_

- **Fix:** Fill both the key and the path, or delete the row. Write paths like `data.items.0.id` or `$.data.items[0].id`; use `@status` and `@header:Name` for status and headers. See [Save values](https://docs.smartestqa.ai/en/automate-steps-api.html#extract-values).

### Problem: The API step ends as ERROR with an SSL or certificate error _(API)_

- **Why:** The API step always verifies certificates; [self-signed and expired certificates are refused](https://docs.smartestqa.ai/en/api-requests-troubleshooting.html#fix-run-ssl).
- **Fix:** Use a valid certificate on the test environment, or an address with one.

## Database, mail and Kafka

### Problem: “Asterisk (*) is not allowed…” / “Query must be in "SELECT ... FROM ..." format.” / “SQL query cannot be empty.” _(Database)_

- **Fix:** Name the columns: `SELECT status, total FROM orders WHERE id = 1`. See [SQL rules](https://docs.smartestqa.ai/en/automate-steps-database.html#sql-rules).

### Problem: “Configuration must be selected.” / “Output values cannot be empty.” _(Database)_

- **Fix:** Pick the connection in **Configuration** and list one output name per column in [**Output Values**](https://docs.smartestqa.ai/en/automate-steps-database.html#outputs). If the list is empty, create the connection on the [Data Source page](https://docs.smartestqa.ai/en/data-source-connections.html#add-db) first.

### Problem: “The column "…" was not found in the table…” / “The table "…" was not found.” _(Database)_

- **Fix:** Names are case-sensitive in many databases. Quote uppercase or reserved names: `"User"`, `"user"`.

### Problem: “Could not connect to the database…” / “Database authentication failed…” _(Database)_

- **Why:** The database is not reachable from the [machine that runs the test](https://docs.smartestqa.ai/en/schedule-where.html#run-environment), or the credentials are wrong.
- **Fix:** Test the connection on the [Data Source page](https://docs.smartestqa.ai/en/data-source-connections.html#add-db). For databases inside your network, [run on your agent](https://docs.smartestqa.ai/en/schedule-where.html#agent) instead of the server.

### Problem: The output variable of a Database step is empty or holds the wrong column _(Database)_

- **Why:** Outputs map to columns by position, not by name, and come from the first row. No row means no value.
- **Fix:** List the outputs in the same order as the SELECT columns and check the query returns a row. See [Output Values](https://docs.smartestqa.ai/en/automate-steps-database.html#outputs).

### Problem: “Timeout: No email with OTP found within … seconds” (also “… with matching link …”, “No matching email …”) _(Mail)_

- **Why:** No new, unread email matched the filters in time. Emails already read, or received more than 30 seconds before the step started, are ignored.
- **Check:** 1. The email reached the [integration’s inbox](https://docs.smartestqa.ai/en/integrations-email.html) (not spam, not another folder).
  2. [**Sender Filter**](https://docs.smartestqa.ai/en/automate-steps-mail.html#fields) and [**Subject Filter**](https://docs.smartestqa.ai/en/automate-steps-mail.html#fields) match the real email.
  3. The code matches [**OTP Pattern (Regex)**](https://docs.smartestqa.ai/en/automate-steps-mail.html#fields): a 4-digit code needs `\b(\d{4})\b`.
- **Fix:** Correct the filters or pattern, raise **Timeout (seconds)** (up to 600), and put the mail step right after the action that sends the email. See [Which emails a step sees](https://docs.smartestqa.ai/en/automate-steps-mail.html#which-emails).

### Problem: “Email integration has not been configured yet. Please configure email from the Integrations page first.” _(Mail)_

- **Fix:** Ask an admin to add the test mailbox on the [Integrations page](https://docs.smartestqa.ai/en/integrations-email.html#set-up), then open the mail dialog again.

### Problem: “Failed to connect to mail server: …” / “Failed to connect to SMTP server: …” / “Failed to send email: …” _(Mail)_

- **Fix:** Check the [integration’s server, port and password](https://docs.smartestqa.ai/en/integrations-email.html#set-up) (many providers need an app password), and that the [machine running the test](https://docs.smartestqa.ai/en/schedule-where.html#run-environment) can reach the mail server.

### Problem: “Kafka consume timed out after …s on topic '…': no matching message found …” _(Kafka)_

- **Check:** The count of messages seen in the message. Zero means nothing arrived on the topic; a higher number means messages arrived but none matched.
- **Fix:** Check the topic name, the [**Match Path (JSONPath)**](https://docs.smartestqa.ai/en/automate-steps-kafka.html#consume) (for example `$.transferId`) and the value; raise the timeout. See [Consume](https://docs.smartestqa.ai/en/automate-steps-kafka.html#consume).

### Problem: “Kafka produce failed: delivery not confirmed within …s …” _(Kafka)_

- **Fix:** The broker did not acknowledge in 10 seconds. Check bootstrap servers, security settings and credentials of the [configuration](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka), and that the broker is reachable from the [machine running the test](https://docs.smartestqa.ai/en/schedule-where.html#run-environment).

### Problem: “No Kafka configuration found…”, “Topic may only contain letters, digits, dot, underscore and dash”, headers not a JSON object _(Kafka)_

- **Fix:** Create the connection on the [Data Source page (Kafka tab)](https://docs.smartestqa.ai/en/data-source-connections.html#add-kafka). Fix the topic name. Write headers as a JSON object: `{"h1":"v1"}`.

## Network

### Problem: “No matching request within …s” _(Network)_

- **Why:** No completed call matched the URL, method and request type in scope. With **Since previous step**, only calls started by the step right before count.
- **Check:** Run a [List](https://docs.smartestqa.ai/en/automate-steps-network.html#list) step at the same place and look at the calls in the [report](https://docs.smartestqa.ai/en/report-steps.html#network-report).
- **Fix:** Correct the URL part, set **Scope** to “Whole session”, raise [**Wait up to (sec)**](https://docs.smartestqa.ai/en/automate-steps-network.html#advanced), or use [Playwright](https://docs.smartestqa.ai/en/project-settings-test-management.html#engine) if Selenium cannot see the call. To go on without it, set [**If no request**](https://docs.smartestqa.ai/en/automate-steps-network.html#advanced) to “Skip and continue”.

### Problem: The Network step ends as WARNING _(Network)_

- **Why:** Failed calls (4xx, 5xx, network failures) or JS errors were seen, and [**On failed calls / JS errors**](https://docs.smartestqa.ai/en/automate-steps-network.html#advanced) is “Mark as warning”.
- **Fix:** Read the errors in the [report](https://docs.smartestqa.ai/en/report-steps.html#network-report). Set the option to “Fail the step” to make them fail the test, or “Ignore”.

### Problem: “URL is required”, “Invalid regular expression”, “Letters, digits and _ only”, “Name is used twice” _(Network)_

- **Fix:** Enter part of the URL (or a prompt), fix the regex when **Match** is regex, and give each variable a unique simple name. See [Save to variable](https://docs.smartestqa.ai/en/automate-steps-network.html#outputs).

## AI steps

### Problem: The **AI step** button is disabled (“Enable '…' in Project Panel → AI Options”) _(AI)_

- **Fix:** Ask an admin to switch on **[Enable AI](https://docs.smartestqa.ai/en/project-settings-ai.html#enable-ai)** and **AI Document Analysis** in the project’s AI options and to [set up the AI provider](https://docs.smartestqa.ai/en/project-settings-ai.html#ai-account). See [Before you start](https://docs.smartestqa.ai/en/automate-steps-ai.html#requirements).

### Problem: “AI step FAILED (STOP_ON_ERROR): …” _(AI)_

- **Why:** The AI answered false (AI Check), could not do the action (AI Do), or the AI service failed. AI steps from the dialog stop the case on failure.
- **Fix:** Look at the [screenshot in the report](https://docs.smartestqa.ai/en/report-steps.html#screenshots): was the page ready? Make the prompt more specific, or replace the step with a [regular action](https://docs.smartestqa.ai/en/maintenance-ai-steps.html#convert) and an [Assertion](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-step).

### Problem: “Please enter a prompt first.” / “Page Name is required” / “Output variable cannot be empty” _(AI)_

- **Fix:** Fill the [prompt and the page](https://docs.smartestqa.ai/en/automate-steps-ai.html#add-ai-step), and a variable name when [Output Value](https://docs.smartestqa.ai/en/automate-steps-ai.html#outputs) is Value.

## Load tests

### Problem: JMeter and k6 are greyed out: “This scenario has browser steps…” _(Load)_

- **Fix:** Put the load test in a test case with [API steps only](https://docs.smartestqa.ai/en/automate-steps-load.html#load-only-rule). [Generate](https://docs.smartestqa.ai/en/automate-steps-load.html#generate) creates that case for you.

### Problem: “No API requests to test yet” / “Add API request steps to the test case first.” _(Load)_

- **Fix:** Add and save the [API steps](https://docs.smartestqa.ai/en/automate-steps-api.html#add-api-step) of the journey first, then open [Generate](https://docs.smartestqa.ai/en/automate-steps-load.html#generate) again.

### Problem: “JMeter could not be found on this machine (…)” / “k6 could not be found on this machine (…)” _(Load)_

- **Fix:** Install JMeter (and Java) on the [machine that runs the test](https://docs.smartestqa.ai/en/schedule-where.html#run-environment), or set `JMETER_HOME`, then restart the [agent](https://docs.smartestqa.ai/en/agent-pool-agents.html). k6 is downloaded automatically unless downloads are turned off; otherwise install it or set `K6_PATH`.

### Problem: “… of … requests failed (…%). Top error: …” _(Load)_

- **Why:** At least one request failed; one is enough to fail the step.
- **Fix:** Open the [report’s requests and responses](https://docs.smartestqa.ai/en/report-load-tests.html#step-report), fix the cause (expired token, wrong data, system overload), or lower the load.

### Problem: “… exceeded the time limit …” / “… above the limit of … users …” _(Load)_

- **Fix:** Reduce duration or users in the [pipeline’s load settings](https://docs.smartestqa.ai/en/schedule-settings.html#mobile-desktop-load). The limits are set by the platform administrator; contact info@smartestqa.ai to change them.

## Mobile and desktop

### Problem: A mobile step can’t find its element (“… did not appear in time”) _(Mobile)_

- **Why:** The screen differs from the recording, the element is off screen, or the locator matches nothing. Mobile steps are [not auto-healed](https://docs.smartestqa.ai/en/maintenance-how-healing-works.html#project-types).
- **Fix:** Add a Scroll or [Wait For Visible](https://docs.smartestqa.ai/en/automate-steps-mobile.html#assert-wait) step before it, and re-capture the element with a stable locator (accessibility id, resource-id). See [Discover › Mobile](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#mobile).

### Problem: A button under the on-screen keyboard can’t be tapped _(Mobile)_

- **Fix:** Add the Global action **Hide Keyboard** after typing, or **Press Enter** to submit. See [Global actions](https://docs.smartestqa.ai/en/automate-steps-mobile.html#global-actions).

### Problem: “The text of "…" did not match the expected value "…" (found: "…")” _(Mobile)_

- **Fix:** Compare the found text with the expected one character by character (currency, spaces). For flexible checks read it with [Get Text](https://docs.smartestqa.ai/en/automate-steps-mobile.html#data) and use an [Assertion](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-step) with Contains.

### Problem: “The device screen is locked…” / “The application under test is not installed on the device.” _(Mobile)_

- **Fix:** Unlock the device and keep the screen awake during runs; install the app (on [Device Farm](https://docs.smartestqa.ai/en/agent-pool-devices.html#devices) through the [App Library](https://docs.smartestqa.ai/en/agent-pool-app-library.html#install-on-devices)) and run again.

### Problem: No desktop agent is found, or the agent is offline _(Desktop)_

- **Fix:** Start the SmartTest agent on the machine with the app and [check it is online](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-status). See [Install the agent](https://docs.smartestqa.ai/en/quick-start-connect.html#install-agent).

### Problem: Typing into a password field does nothing _(Desktop)_

- **Fix:** Use **Type Key by Key**; it types like a real keyboard. See [Input and keys](https://docs.smartestqa.ai/en/automate-steps-desktop.html#input).

### Problem: The step acts on the wrong window _(Desktop)_

- **Fix:** Add **Switch Window** with part of the target window’s title before the step. See [App and window](https://docs.smartestqa.ai/en/automate-steps-desktop.html#app-window).

## Still stuck

Write to [info@smartestqa.ai](mailto:info@smartestqa.ai) with the test case name, the run (Dry Run time or [pipeline report link](https://docs.smartestqa.ai/en/report-summary.html#share-report)) and the step message.
