1. Docs
  2. Reference
  3. Step reference
  4. Step troubleshooting

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.

13 min read Updated CustomersAdmins

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#

“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 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: 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)?
Fix
Fix or add a locator in Action Detail, preferring id or data-testid. Add a wait for slow pages (Waits). For a new tab in Selenium, switch tabs in a Python step. Auto-heal does not run on login pages or when the app returns 401, 403 or 5xx.
Type added the text after the old valueElement
Why
Type does not clear the field; it appends.
Fix
Use a Clear & Type action for that field: replace the step’s action with one of type Clear & Type and enter the value again. Changing the type of the shared action itself changes every test case that uses it.
“Failed to select option from "…"”Element
Why
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 to open it and a Click on the option.
The test went on after a failed Visibility CheckChecks
Why
A failed Visibility Check marks the step FAILED but does not stop the test case.
Fix
Where the flow must stop, read the value with Get and use an Assertion, which stops the case.
“Text or locator is required for visibility check.”Checks
Fix
Give the step an action with a locator, or an expected text value, or both.
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) 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, make sure the step that sets it runs first.

Checks#

“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.
“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 if you only check presence.
“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 that reads it. See Transforms.
An assertion fails although the values look the sameAssertion
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. See Comparison rules.

Variables and code#

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, skipped branch, failed), or it runs after this step.
Check
The exact output name of the producing step (case matters) and its position in the list.
Fix
Use the picker icon to insert the reference instead of typing it. See Reference syntax.
“Parameter key can only contain letters, digits and underscore”Variables
Fix
Rename the Get or Global parameter key: order_id, not order-id or order id.
“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. See Steps that produce variables.
“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, or remove the step. See Python or JavaScript.
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.
“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.
“[IF] Condition could not be evaluated”Code
Why
The condition raised an error, typically comparing text with a number.
Fix
Wrap numbers: int({{tc:count}}) > 10; quote text: "{{tc:status}}" == "PAID".
“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#

The API step passed although the API returned 404 or 500API
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. See Check the status code.
“Unsupported HTTP method: HEAD” (or OPTIONS) at run timeAPI
Why
The editor 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.
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.
Fix
Add JSON paths by hand (plus icon) and test the step with a Dry Run on your agent. See Send.
“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.
The API step ends as ERROR with an SSL or certificate errorAPI
Why
The API step always verifies certificates; self-signed and expired certificates are refused.
Fix
Use a valid certificate on the test environment, or an address with one.

Database, mail and Kafka#

“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.
“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. If the list is empty, create the connection on the Data Source page first.
“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".
“Could not connect to the database…” / “Database authentication failed…”Database
Why
The database is not reachable from the machine that runs the test, or the credentials are wrong.
Fix
Test the connection on the Data Source page. For databases inside your network, run on your agent instead of the server.
The output variable of a Database step is empty or holds the wrong columnDatabase
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.
“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 (not spam, not another folder).
  2. Sender Filter and Subject Filter match the real email.
  3. The code matches OTP Pattern (Regex): 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.
“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, then open the mail dialog again.
“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 (many providers need an app password), and that the machine running the test can reach the mail server.
“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) (for example $.transferId) and the value; raise the timeout. See Consume.
“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, and that the broker is reachable from the machine running the test.
“No Kafka configuration found…”, “Topic may only contain letters, digits, dot, underscore and dash”, headers not a JSON objectKafka
Fix
Create the connection on the Data Source page (Kafka tab). Fix the topic name. Write headers as a JSON object: {"h1":"v1"}.

Network#

“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 step at the same place and look at the calls in the report.
Fix
Correct the URL part, set Scope to “Whole session”, raise Wait up to (sec), or use Playwright if Selenium cannot see the call. To go on without it, set If no request to “Skip and continue”.
The Network step ends as WARNINGNetwork
Why
Failed calls (4xx, 5xx, network failures) or JS errors were seen, and On failed calls / JS errors is “Mark as warning”.
Fix
Read the errors in the report. Set the option to “Fail the step” to make them fail the test, or “Ignore”.
“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.

AI steps#

The AI step button is disabled (“Enable '…' in Project Panel → AI Options”)AI
Fix
Ask an admin to switch on Enable AI and AI Document Analysis in the project’s AI options and to set up the AI provider. See Before you start.
“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: was the page ready? Make the prompt more specific, or replace the step with a regular action and an Assertion.
“Please enter a prompt first.” / “Page Name is required” / “Output variable cannot be empty”AI
Fix
Fill the prompt and the page, and a variable name when Output Value is Value.

Load tests#

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. Generate creates that case for you.
“No API requests to test yet” / “Add API request steps to the test case first.”Load
Fix
Add and save the API steps of the journey first, then open Generate again.
“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, or set JMETER_HOME, then restart the agent. k6 is downloaded automatically unless downloads are turned off; otherwise install it or set K6_PATH.
“… 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, fix the cause (expired token, wrong data, system overload), or lower the load.
“… exceeded the time limit …” / “… above the limit of … users …”Load
Fix
Reduce duration or users in the pipeline’s load settings. The limits are set by the platform administrator; contact info@smartestqa.ai to change them.

Mobile and desktop#

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.
Fix
Add a Scroll or Wait For Visible step before it, and re-capture the element with a stable locator (accessibility id, resource-id). See Discover › Mobile.
A button under the on-screen keyboard can’t be tappedMobile
Fix
Add the Global action Hide Keyboard after typing, or Press Enter to submit. See Global actions.
“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 and use an Assertion with Contains.
“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 through the App Library) and run again.
No desktop agent is found, or the agent is offlineDesktop
Fix
Start the SmartTest agent on the machine with the app and check it is online. See Install the agent.
Typing into a password field does nothingDesktop
Fix
Use Type Key by Key; it types like a real keyboard. See Input and keys.
The step acts on the wrong windowDesktop
Fix
Add Switch Window with part of the target window’s title before the step. See App and window.

Still stuck#

Write to info@smartestqa.ai with the test case name, the run (Dry Run time or pipeline report link) and the step message.

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 017fcec