Comprehensive Troubleshooting Guide for SmartUI

This comprehensive troubleshooting guide covers common issues you may encounter when using SmartUI for visual regression testing. Each issue includes symptoms, possible causes, and step-by-step solutions.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

Project token is set correctly (PROJECT_TOKEN environment variable)
SmartUI CLI is installed and up-to-date (npx smartui --version)
Configuration file (.smartui.json) exists and is valid JSON
Network connectivity to TestMu AI servers
Project exists in SmartUI dashboard
Credentials (for Hooks) are set correctly (LT_USERNAME, LT_ACCESS_KEY)
Project name matches exactly (case-sensitive)

Troubleshooting by Category

Verified

Issue: Screenshots Not Appearing in Dashboard

Symptoms:

Tests run successfully but no screenshots appear in SmartUI dashboard
Build appears empty in dashboard
No error messages in logs

Possible Causes:

Project token not set or incorrect
Project name mismatch
Network connectivity issues
CLI not installed or outdated
Configuration file issues

Solutions:

Verify Project Token:

MacOS/Linux
Windows CMD
PowerShell

echo $PROJECT_TOKEN

If empty, set it:

export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"

echo %PROJECT_TOKEN%

If empty, set it:

set PROJECT_TOKEN="123456#1234abcd-****-****-****-************"

echo $env:PROJECT_TOKEN

If empty, set it:

$env:PROJECT_TOKEN="123456#1234abcd-****-****-****-************"

Check Project Name: Verify project name in dashboard matches exactly (case-sensitive)

Verify SmartUI CLI Installation:

npx smartui --version

If outdated, update:

npm install -g @lambdatest/smartui-cli@latest

Check Network Connectivity:
```
curl -I https://smartui.lambdatest.com
```
Review Test Execution Logs: Look for error messages or warnings in test output

Related Documentation: Project Settings, Running Your First Project

Issue: "Project Not Found" Error

Symptoms:

Error message: "Project not found" or "Invalid project token"
Tests fail to start
Authentication errors

Possible Causes:

Incorrect project token
Project deleted or renamed
Token from wrong project
Extra spaces or quotes in token
Token format incorrect

Solutions:

Verify Project Exists:
- Log into SmartUI Dashboard
- Check if project exists
- Verify project name matches
Copy Token Directly:
- Go to Project Settings in dashboard
- Copy project token directly (don't type manually)
- Ensure token includes project ID prefix (e.g., 123456#...)
Check Token Format:
- Token should be in format: PROJECT_ID#TOKEN_VALUE
- No extra spaces before or after
- No quotes needed when setting environment variable
Verify Token Scope:
- Ensure token is from the correct project
- Check if project was moved or renamed

Related Documentation: Project Settings

Issue: Credentials Not Working (Hooks)

Symptoms:

Tests fail with authentication errors
"Invalid credentials" message
Connection refused errors

Possible Causes:

LT_USERNAME or LT_ACCESS_KEY not set
Incorrect credentials
Credentials from wrong account
Environment variables not exported

Solutions:

Verify Credentials Are Set:

MacOS/Linux
Windows CMD
PowerShell

echo $LT_USERNAME
echo $LT_ACCESS_KEY

echo %LT_USERNAME%
echo %LT_ACCESS_KEY%

echo $env:LT_USERNAME
echo $env:LT_ACCESS_KEY

Get Correct Credentials:
- Log into TestMu AI Dashboard
- Click "Access Key" button
- Copy username and access key

Set Credentials Correctly:

MacOS/Linux
Windows CMD
PowerShell

export LT_USERNAME="your_username"
export LT_ACCESS_KEY="your_access_key"

set LT_USERNAME="your_username"
set LT_ACCESS_KEY="your_access_key"

$env:LT_USERNAME="your_username"
$env:LT_ACCESS_KEY="your_access_key"

Related Documentation: Selenium Visual Regression, Playwright Visual Regression

Issue: CLI Installation and Version Management

Symptoms:

"command not found: smartui" error
CLI commands not working
Using outdated CLI version
Inconsistent behavior between terminals

Possible Causes:

CLI not installed globally
CLI installed locally but not accessible
Using outdated version
Multiple versions installed
PATH not configured correctly

Solutions:

Understanding Global vs Local Installation:

Global Installation (-g flag):
- Installs CLI system-wide, accessible from any terminal
- Command available as smartui directly
- Requires administrator/sudo privileges
- Best for: Single user, consistent environment

   npm install -g @lambdatest/smartui-cli

Local Installation (without -g):

Installs CLI in project's node_modules
Access via npx smartui or ./node_modules/.bin/smartui
No admin privileges needed
Best for: Project-specific versions, CI/CD pipelines

   npm install @lambdatest/smartui-cli
   npx smartui --version

Installing Latest Versions:

SmartUI CLI:

# Global installation (latest)
npm install -g @lambdatest/smartui-cli@latest

# Local installation (latest)
npm install @lambdatest/smartui-cli@latest

# Using npx (always uses latest)
npx @lambdatest/smartui-cli@latest --version

SmartUI Storybook CLI:

# Global installation (latest)
npm install -g @lambdatest/smartui-storybook@latest

# Local installation (latest)
npm install @lambdatest/smartui-storybook@latest

# Using npx (always uses latest)
npx @lambdatest/smartui-storybook@latest --version

Checking Current Version:

# If installed globally
smartui --version

# If installed locally or using npx
npx smartui --version

Updating to Latest Version:

# Global update
npm update -g @lambdatest/smartui-cli

# Local update
npm update @lambdatest/smartui-cli

# Force reinstall latest
npm install -g @lambdatest/smartui-cli@latest --force

Resolving "Command Not Found":

If installed globally:

Verify npm global bin is in PATH:

echo $PATH | grep -i node
npm config get prefix

Add to PATH if missing:

# macOS/Linux - Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"

If installed locally:

Always use npx prefix:

npx smartui --version
npx smartui exec -- <command>

Or use direct path:
```
./node_modules/.bin/smartui --version
```

Best Practices:
- For Development: Use local installation with npx for project-specific versions
- For CI/CD: Use npx @lambdatest/smartui-cli@latest to ensure latest version
- For Global Use: Install globally with -g flag for convenience
- Version Pinning: Use specific versions in package.json for reproducible builds

Related Documentation: CLI Complete Reference, Running Your First Project

Issue: Screenshots Show Blank or Incorrect Content

Symptoms:

Screenshots captured but show blank pages
Partial content missing
Incorrect viewport size
Elements not rendered

Possible Causes:

Page not fully loaded
JavaScript not executed
Viewport size issues
Timing issues
Lazy loading not handled

Solutions:

Add Explicit Waits (Framework-specific):

Selenium (Java):

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.presenceOfElementLocated(By.id("content")));
SmartUISnapshot.smartuiSnapshot(driver, "Screenshot Name");

Playwright (JavaScript):

await page.goto('https://example.com');
await page.waitForSelector('#content', { state: 'visible' });
await page.waitForLoadState('networkidle');
await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name");

Cypress:

cy.visit('https://example.com');
cy.get('#content').should('be.visible');
cy.wait(2000); // Wait for animations
cy.smartuiSnapshot('Screenshot Name');

Enable JavaScript in Configuration:

{
  "enableJavaScript": true,
  "waitForTimeout": 2000,
  "waitForPageRender": 5000
}

Increase Wait Timeouts:

{
  "waitForTimeout": 3000,
  "waitForPageRender": 10000
}

Verify Viewport Size:
- Check viewport dimensions in configuration
- Ensure viewport matches expected page layout
- Test with different viewport sizes
Handle Lazy Loading:
- Scroll to bottom before screenshot
- Use waitForPageRender option
- See Handling Lazy Loading for details

Related Documentation: Handling Lazy Loading, Configuration Options

Issue: Screenshot Names Not Matching Baseline

Symptoms:

Screenshots appear as "New" instead of comparing with baseline
Baseline comparison not working
Screenshot names inconsistent

Possible Causes:

Screenshot name changed
Baseline doesn't exist
Name contains special characters
Case sensitivity issues

Solutions:

Ensure Consistent Naming:
- Use same screenshot names across test runs
- Document naming convention
- Avoid dynamic names with timestamps
Verify Baseline Exists:
- Check SmartUI dashboard for baseline build
- Ensure baseline was approved
- Verify baseline build name matches
Avoid Special Characters:
- Use alphanumeric characters and hyphens
- Avoid spaces, special characters, or unicode
- Example: HomePage-Header not HomePage Header!
Check Case Sensitivity:
- Screenshot names are case-sensitive
- HomePage ≠ homepage
- Use consistent casing

Use Meaningful Names:

// Good
cy.smartuiSnapshot('ProductPage-MainContent');
cy.smartuiSnapshot('CheckoutPage-PaymentForm');

// Bad
cy.smartuiSnapshot('screenshot1');
cy.smartuiSnapshot('test-' + Date.now());

Related Documentation: Baseline Management

Issue: High Mismatch Percentage or False Positives

Symptoms:

Mismatch percentage higher than expected
Many false positives in comparisons
Dynamic content causing issues

Possible Causes:

Dynamic content not ignored
Threshold settings too strict
Rendering differences
Baseline issues

Solutions:

Use ignoreDOM for Dynamic Content:

let options = {
  ignoreDOM: {
    id: ["timestamp", "user-id", "session-token"],
    class: ["dynamic-content", "ad-banner"],
    cssSelector: ["[data-testid='timestamp']"]
  }
};
smartuiSnapshot(driver, "Screenshot Name", options);

Adjust Pixel Threshold:
- Go to Project Settings
- Adjust Pixel Threshold (Relaxed/Recommended/Strict)
- Or set custom threshold value
Use Smart Ignore:
- Enable Smart Ignore in project settings
- Automatically ignores layout shifts and displacements
Review Comparison Settings:
- Check Error Highlight Color
- Adjust Custom Mismatch Acceptance
- Review Advanced Comparison Settings
Handle Dynamic Data Properly:
- See Handling Dynamic Data for comprehensive guide
- Use selectDOM for focused comparisons
- Document ignored elements

Related Documentation: Handling Dynamic Data, Project Settings, Smart Ignore

Issue: Build Execution Fails

Symptoms:

npx smartui exec command fails
Tests don't start
Configuration errors

Possible Causes:

Missing or incorrect configuration file
Invalid JSON in configuration
Port conflicts
Permission issues
CLI version issues

Solutions:

Verify Configuration File Exists:

ls -la .smartui.json

If missing, create it:

npx smartui config:create .smartui.json

Validate JSON Syntax:
```
cat .smartui.json | python -m json.tool
```
Or use online JSON validator

Check Port Availability:

# Check if port 5000 is in use
lsof -i :5000

Use different port:

npx smartui exec -P 5001 -- <command>

Check File Permissions:
```
chmod 644 .smartui.json
```

Update CLI:

npm install -g @lambdatest/smartui-cli@latest

Check CLI Help:

npx smartui --help
npx smartui exec --help

Related Documentation: CLI Documentation, Configuration Options

Issue: Dependencies Not Resolving

Symptoms:

Package manager cannot find dependencies
Installation fails
Version conflicts

Possible Causes:

Incorrect dependency version
Package registry access issues
Network connectivity problems
Node version mismatch

Solutions:

Check Latest Versions:

npm packages:

npm view @lambdatest/smartui-cli version
npm view @lambdatest/playwright-driver version

Maven (Java):

Check Maven Central

pip (Python):

pip index versions lambdatest-selenium-driver

Clear Package Manager Cache:

npm:

npm cache clean --force

Maven:

mvn clean

pip:

pip cache purge

Verify Internet Connectivity:
```
ping registry.npmjs.org
```
Check Node Version (for npm):
```
node --version
```
Ensure Node.js v20.3+ is installed (required for SmartUI CLI v4.x.x)
Use Package Lock Files:
- Use package-lock.json for npm
- Use requirements.txt with pinned versions for pip
- Use pom.xml with specific versions for Maven

Related Documentation: SDK Documentation, CLI Documentation

Issue: Pipeline/Workflow Fails with "Secret/Variable Not Found"

Symptoms:

CI/CD pipeline fails
Error about missing secrets/variables
Authentication failures in pipeline

Possible Causes:

Secrets/variables not created
Secret/variable names don't match
Secrets/variables not accessible
Scope issues

Solutions:

Verify Secrets/Variables Exist:

GitHub Actions:
- Go to Settings → Secrets and variables → Actions
- Verify LT_USERNAME, LT_ACCESS_KEY, PROJECT_TOKEN exist
GitLab:
- Go to Settings → CI/CD → Variables
- Check variables are set
Bitbucket:
- Go to Repository Settings → Pipelines → Repository variables
- Verify variables exist
Check Variable Names:
- Ensure exact match (case-sensitive)
- No extra spaces
- Correct prefix/suffix
Verify Scope:
- Check if variables are repository, group, or instance level
- Ensure variables accessible to pipeline
- Check protected branch settings

Pass Variables to Steps:

GitHub Actions:

env:
  PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}

GitLab:

variables:
  PROJECT_TOKEN: $PROJECT_TOKEN

Related Documentation: GitHub Actions Integration, GitLab Integration, Bitbucket Integration

Issue: Tests Run But No Results in Dashboard (CI/CD)

Symptoms:

Pipeline completes successfully
No screenshots in SmartUI dashboard
Build appears empty

Possible Causes:

Incorrect PROJECT_TOKEN
Project name mismatch
Network issues
Workflow step failure

Solutions:

Verify PROJECT_TOKEN:
- Check token in SmartUI Project Settings
- Ensure token includes project ID prefix
- Verify token is set as secret/variable
Check Pipeline Logs:
- Review CI/CD logs for errors
- Look for SmartUI CLI output
- Check for network errors
Verify Network Connectivity:
- Ensure CI/CD runner can access TestMu AI servers
- Check firewall/proxy settings
- Verify DNS resolution
Check SmartUI CLI Step:
- Ensure npx smartui exec step completed
- Verify command syntax is correct
- Check for timeout issues

Related Documentation: CI/CD Integration Guides

Issue: Configuration File Errors

Symptoms:

"must NOT have additional properties" error
Invalid JSON errors
Configuration not applied

Possible Causes:

Invalid JSON syntax
Properties in wrong location
Unsupported options
File encoding issues

Solutions:

Validate JSON Syntax:
```
cat .smartui.json | python -m json.tool
```
Check Property Placement:
- customCSS must be at top level, not inside web
- Verify structure matches Configuration Options
Review Supported Options:
- Check Configuration Options for valid properties
- Remove unsupported options
- Verify option names are correct
Check File Encoding:
- Ensure file is UTF-8 encoded
- No BOM (Byte Order Mark)
- Use standard line endings

Related Documentation: Configuration Options, Custom CSS

Issue: Environment Variables Not Persisting or Not Working

Symptoms:

Environment variables work in one terminal but not another
Variables reset after closing terminal
Variables not available in VS Code terminal
Variables not working in CI/CD pipelines
"Variable not found" errors

Possible Causes:

Variables set only in current session
Shell startup file not configured
VS Code terminal not loading shell config
Variables not exported correctly
Different shell environments

Solutions:

Making Environment Variables Persistent:

To keep environment variables consistent across all terminals, configure them in your shell's startup file:

Bash (.bashrc)
Zsh (.zshrc)
PowerShell ($PROFILE)

# Edit ~/.bashrc
nano ~/.bashrc

# Add your environment variables
export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
export LT_USERNAME="your_username"
export LT_ACCESS_KEY="your_access_key"

# Reload the configuration
source ~/.bashrc

# Edit ~/.zshrc
nano ~/.zshrc

# Add your environment variables
export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
export LT_USERNAME="your_username"
export LT_ACCESS_KEY="your_access_key"

# Reload the configuration
source ~/.zshrc

# Check if profile exists
Test-Path $PROFILE

# Create profile if it doesn't exist
if (!(Test-Path $PROFILE)) {
    New-Item -Type File -Path $PROFILE -Force
}

# Edit profile
notepad $PROFILE

# Add your environment variables
$env:PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
$env:LT_USERNAME="your_username"
$env:LT_ACCESS_KEY="your_access_key"

# Reload the profile
. $PROFILE

Configuring Environment Variables in VS Code:

If environment variables don't work in VS Code terminals, configure them in VS Code settings:

Option 1: User Settings (settings.json)

Open VS Code settings (Ctrl+, or Cmd+,) and add:

   {
     "terminal.integrated.env.linux": {
       "PROJECT_TOKEN": "123456#1234abcd-****-****-****-************",
       "LT_USERNAME": "your_username",
       "LT_ACCESS_KEY": "your_access_key"
     },
     "terminal.integrated.env.osx": {
       "PROJECT_TOKEN": "123456#1234abcd-****-****-****-************",
       "LT_USERNAME": "your_username",
       "LT_ACCESS_KEY": "your_access_key"
     },
     "terminal.integrated.env.windows": {
       "PROJECT_TOKEN": "123456#1234abcd-****-****-****-************",
       "LT_USERNAME": "your_username",
       "LT_ACCESS_KEY": "your_access_key"
     }
   }

Option 2: Workspace Settings (.vscode/settings.json)

Create or edit .vscode/settings.json in your project root:

   {
     "terminal.integrated.env.linux": {
       "PROJECT_TOKEN": "123456#1234abcd-****-****-****-************"
     },
     "terminal.integrated.env.osx": {
       "PROJECT_TOKEN": "123456#1234abcd-****-****-****-************"
     },
     "terminal.integrated.env.windows": {
       "PROJECT_TOKEN": "123456#1234abcd-****-****-****-************"
     }
   }

Note: Restart VS Code or reload the window after making changes.

Using .env Files:

For project-specific environment variables, use a .env file:

Create .env file in project root:
```
PROJECT_TOKEN=123456#1234abcd-****-****-****-************
LT_USERNAME=your_username
LT_ACCESS_KEY=your_access_key
```
Load .env file automatically:

For Node.js projects:
- Install dotenv package:
```
npm install dotenv
```
- Load in your scripts:
```
require('dotenv').config();
```
- Or use dotenv-cli:
```
npm install -g dotenv-cli
dotenv smartui exec -- <command>
```
For Python projects:
- Install python-dotenv:
```
pip install python-dotenv
```
- Load in your scripts:
```
from dotenv import load_dotenv
load_dotenv()
```
For VS Code:
- Install "DotENV" extension
- Or use "Python" extension which auto-loads .env files
Verifying Environment Variables:

MacOS/Linux
Windows CMD
PowerShell

# Check if variable is set
echo $PROJECT_TOKEN
echo $LT_USERNAME
echo $LT_ACCESS_KEY

# List all SmartUI-related variables
env | grep -E "PROJECT_TOKEN|LT_USERNAME|LT_ACCESS_KEY|SMARTUI"

# Check if variable is set
echo %PROJECT_TOKEN%
echo %LT_USERNAME%
echo %LT_ACCESS_KEY%

# List all environment variables
set | findstr /i "PROJECT_TOKEN LT_USERNAME LT_ACCESS_KEY SMARTUI"

# Check if variable is set
echo $env:PROJECT_TOKEN
echo $env:LT_USERNAME
echo $env:LT_ACCESS_KEY

# List all SmartUI-related variables
Get-ChildItem Env: | Where-Object { $_.Name -like "*PROJECT_TOKEN*" -or $_.Name -like "*LT_*" -or $_.Name -like "*SMARTUI*" }

Troubleshooting Common Issues:

Issue: Variables not available after adding to startup file
- Solution: Restart terminal or run source ~/.bashrc / source ~/.zshrc
Issue: VS Code terminal not picking up variables
- Solution: Add to VS Code settings.json as shown above, then restart VS Code
Issue: Variables work in terminal but not in scripts
- Solution: Ensure variables are exported (use export in bash/zsh)
Issue: Different values in different terminals
- Solution: Use startup file configuration instead of session-only exports
Issue: .env file not loading
- Solution: Verify file is in project root, check file permissions, ensure extension/package is installed
Best Practices:
- Never commit sensitive data: Add .env to .gitignore
- Use different values per environment: Development, staging, production
- Document required variables: List in README or documentation
- Use CI/CD secrets: Store sensitive values in CI/CD platform secrets/variables
- Validate on startup: Check if required variables are set before running tests

Related Documentation: CLI Environment Variables, Running Your First Project

Issue: Proxy Configuration Not Working

Symptoms:

Tests fail behind proxy
Connection timeouts
Authentication issues

Possible Causes:

Proxy not configured
Authentication not set
Proxy URL incorrect
Network restrictions

Solutions:

Set Proxy Environment Variables:

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"

For Authenticated Proxy:
- Currently, SmartUI CLI may not support proxy authentication
- Use proxy without authentication if possible
- Contact support for proxy authentication support
Verify Proxy Settings:
```
echo $HTTP_PROXY
echo $HTTPS_PROXY
```

Related Documentation: CLI Environment Variables

Issue: Tunnel Connection Issues

Symptoms:

Tunnel connection fails
Localhost not accessible
Connection timeouts

Possible Causes:

Tunnel not started
Port conflicts
Firewall blocking
Network issues

Solutions:

Start Tunnel:

./LT --user <username> --key <access_key>

Verify Tunnel Status:
- Check tunnel is running
- Verify tunnel shows as "Active" in dashboard
Check Port Availability:
- Ensure no conflicts on tunnel ports
- Check firewall settings

Related Documentation: Tunnel Documentation, SDK Tunnel

Error Message Reference

When a SmartUI CLI command fails, it prints a plain-text message. This section lists those messages exactly as the CLI prints them, what each one means, and what to do.

Some messages end with details from your run, such as a file name or the reason the server gave. Those details are shown here as …. For many failures, the CLI prints the underlying reason just above the message.

Documented for @lambdatest/smartui-cli v4.1.81.

Authentication and Setup

Authentication failed

Field	Value
Message	`Authentication failed`
What happened	The CLI could not authenticate with SmartUI. When the server gives a reason, the CLI prints that reason instead.
What to do	Check `LT_USERNAME`, `LT_ACCESS_KEY`, and your project token. The project token uses the format `PROJECT_ID#TOKEN_VALUE`. See Project Not Found above.

SmartUI capabilities are missing in env variables or in driver capabilities

Field	Value
Message	`SmartUI capabilities are missing in env variables or in driver capabilities`
What happened	An SDK run needed to create a build, but no SmartUI settings were found in environment variables or in driver capabilities.
What to do	Set the SmartUI environment variables before the run, or pass them in your driver capabilities. See SmartUI SDK Environment Variables.

Configuration File

Invalid config; web config must have either customViewports or both browsers and viewports

Field	Value
Message	`Invalid config; web config must have either customViewports or both browsers and viewports`
What happened	The `web` block in your config does not say which screens to capture.
What to do	In the `web` block, set either `customViewports`, or both `browsers` and `viewports`.

Invalid config; rejectionThreshold must be greater than approvalThreshold

Field	Value
Message	`Invalid config; rejectionThreshold must be greater than approvalThreshold`
What happened	The rejection threshold is not greater than the approval threshold.
What to do	Set `rejectionThreshold` to a value higher than `approvalThreshold`.

customViewports is only supported for the exec command. Use browsers and viewports instead.

Field	Value
Message	`customViewports is only supported for the exec command. Use browsers and viewports instead.`
What happened	`customViewports` was set for a command other than `exec`.
What to do	Define `browsers` and `viewports` instead, or use the exec command.

No URLs found in the specified config file

Field	Value
Message	`No URLs found in the specified config file -> …`
What happened	The file listing the URLs to capture contains none.
What to do	Add at least one URL to the file. See Capture Static URLs via CLI.

Web Static Config file not found

Field	Value
Message	`Web Static Config file … not found.`
What happened	The static config file named in the command does not exist at that path.
What to do	Check the path, or run the command from the directory that contains the file.
Also seen as	`Invalid Web Static Config; …`

Invalid customCSS file type

Field	Value
Message	`Invalid customCSS file type: … Only .css files are supported.`
What happened	`customCSS` points to a file that is not a `.css` file.
What to do	Point `customCSS` at an existing `.css` file.
Also seen as	`customCSS file not found: …` · `customCSS path is not a file: …` · `customCSS must be a non-empty string` · `customCSS cannot be empty`

Builds and Uploads

SmartUI build creation failed

Field	Value
Message	`SmartUI build creation failed`
What happened	The CLI could not create a build.
What to do	Read the reason printed with it. `Build creation failed: Build ID is empty` means the server returned no build ID; run the command again.
Also seen as	`Error while creation of build: …` · `Build creation failed: Build ID is empty`

Finalize build failed

Field	Value
Message	`Finalize build failed`
What happened	The build could not be finalized. The reason is printed just above the message.
What to do	Fix the problem it names, then run the command again.

Uploading screenshots failed

Field	Value
Message	`Uploading screenshots failed`
What happened	The screenshots could not be uploaded. The reason is printed just above the message.
What to do	Fix the problem it names, then run the upload again. See Upload your Screenshots via CLI.

PDF upload failed

Field	Value
Message	`PDF upload failed`
What happened	The PDFs could not be uploaded. The reason is printed just above the message.
What to do	Fix the problem it names, then run the upload again. See Upload PDFs via CLI.

Project ID not found to fetch PDF results

Field	Value
Message	`Project ID not found to fetch PDF results`
What happened	The CLI had no project ID when it tried to fetch PDF results.
What to do	Run the upload again. If it happens again, contact support.

Snapshot processing failed

Field	Value
Message	`Snapshot processing failed`
What happened	A snapshot was still processing after the CLI waited about five minutes for it.
What to do	Run the command again. If it happens again, contact support.
Also seen as	`Snapshot Failed`, when processing finished with a failure

Local Server and Network

SmartUI server setup failed

Field	Value
Message	`SmartUI server setup failed`
What happened	The local SmartUI server that receives SDK snapshots could not start. The reason is printed just above the message.
What to do	Fix the problem it names, then run the command again.

No available ports found in range

Field	Value
Message	`No available ports found in range …`
What happened	Every port in the range the CLI tried for its local server was in use.
What to do	Free a port in the range shown in the message, then run the command again.

Invalid port number. Port number must be an integer between 1 and 65535.

Field	Value
Message	`Invalid port number. Port number must be an integer between 1 and 65535.`
What happened	The value passed to `--port` is not a valid port.
What to do	Pass a whole number from 1 to 65535.

Invalid proxy URL

Field	Value
Message	`Invalid proxy URL:`
What happened	The value of the `SMARTUI_API_PROXY` environment variable could not be read as a URL.
What to do	Set `SMARTUI_API_PROXY` to a proxy address such as `proxy.example.com:8080`, or to a full URL that starts with `http`.

Merging Builds and Branches

Merging two similar build is not possible

Field	Value
Message	`Merging two similar build is not possible`
What happened	The source and target of the merge are the same build.
What to do	Choose two different builds.

Merging two similar branch is not possible

Field	Value
Message	`Merging two similar branch is not possible`
What happened	The source and target of the merge are the same branch.
What to do	Choose two different branches. See Branching Strategy.

Error: The --source option cannot be empty.

Field	Value
Message	`Error: The --source option cannot be empty.`
What happened	A merge was started without a source.
What to do	Pass both `--source` and `--target`.
Also seen as	`Error: The --target option cannot be empty.`

Merging SmartUI build failed

Field	Value
Message	`Merging SmartUI build failed`
What happened	The merge did not complete. The reason is printed just above the message.
What to do	Fix the problem it names, then run the merge again.
Also seen as	`Error while initiating merging process: …` · `Error while fetching buildInfo: …` · `Error while fetching branch Info: …`

Figma

Errors about the Figma token and about Figma config validation are documented on the SmartUI Figma App CLI page: see Understanding the Tokens and Credentials and The config file is rejected.

Missing LT_USERNAME in Environment Variables

Field	Value
Message	`Missing LT_USERNAME in Environment Variables`
What happened	A Figma command found `LT_USERNAME` set to an empty value.
What to do	Set it to your username, or leave it unset. See Understanding the Tokens and Credentials.
Also seen as	`Missing LT_ACCESS_KEY in Environment Variables`, the same check for `LT_ACCESS_KEY`

No Figma configuration found in config file

Field	Value
Message	`No Figma configuration found in config file`
What happened	A Figma command ran against a config file with no Figma section.
What to do	Add the Figma configuration to your config file. See SmartUI Figma CLI.

Mismatch in Figma Ids and Screenshot Viewports in figma config

Field	Value
Message	`Mismatch in Figma Ids and Screenshot Viewports in figma config`
What happened	The number of Figma IDs does not match the number of screenshot viewports.
What to do	Give every Figma ID a matching viewport.

Uploading Figma designs failed

Field	Value
Message	`Uploading Figma designs failed`
What happened	The Figma designs could not be uploaded.
What to do	Run the command again. If it happens again, contact support.
Also seen as	`Uploading Web Figma Screenshots failed` · `Uploading App Figma Screenshots failed`

Timeout: Fetching figma results took more than 5 minutes.

Field	Value
Message	`Timeout: Fetching figma results took more than 5 minutes.`
What happened	The CLI stopped waiting for Figma comparison results.
What to do	Run the command again.
Also seen as	`Stopping execution after 5 minutes.`

SDK

contextId and snapshotName are required parameters

Field	Value
Message	`contextId and snapshotName are required parameters`
What happened	A snapshot request reached the CLI without a `contextId` or a `snapshotName`.
What to do	Send both values with every snapshot request.

No buildId found for contextId

Field	Value
Message	`No buildId found for contextId: …`
What happened	A snapshot finished processing, but no build was linked to it.
What to do	Run the command again. If it happens again, contact support.

Page instance not available

Field	Value
Message	`Page instance not available`
What happened	The CLI tried to run a page script, but its browser page was not available.
What to do	Run the command again. If it happens again, contact support.

Getting Additional Help

If you encounter issues not covered in this guide:

Check Related Documentation:
- Review framework-specific documentation
- Check Project Settings
- Review Configuration Options
Search Existing Issues:
- Check TestMu AI Support
- Review community forums
- Search knowledge base
Contact Support:
- Email: support@testmuai.com
- 24/7 Chat Support
- Include error messages, logs, and configuration details
Provide Diagnostic Information:
- CLI version: npx smartui --version
- Configuration file (redact sensitive data)
- Error messages and logs
- Steps to reproduce

Quick Diagnostic Checklist​

Troubleshooting by Category​

Issue: "Project Not Found" Error​

Issue: Credentials Not Working (Hooks)​

Issue: CLI Installation and Version Management​

Error Message Reference​

Authentication and Setup​

Authentication failed​

SmartUI capabilities are missing in env variables or in driver capabilities​

Configuration File​

Invalid config; web config must have either customViewports or both browsers and viewports​

Invalid config; rejectionThreshold must be greater than approvalThreshold​

customViewports is only supported for the exec command. Use browsers and viewports instead.​

No URLs found in the specified config file​

Web Static Config file not found​

Invalid customCSS file type​

Builds and Uploads​

SmartUI build creation failed​

Finalize build failed​

Uploading screenshots failed​

PDF upload failed​

Project ID not found to fetch PDF results​

Snapshot processing failed​

Local Server and Network​

SmartUI server setup failed​

No available ports found in range​

Invalid port number. Port number must be an integer between 1 and 65535.​

Invalid proxy URL​

Merging Builds and Branches​

Merging two similar build is not possible​

Merging two similar branch is not possible​

Error: The --source option cannot be empty.​

Merging SmartUI build failed​

Figma​

Missing LT_USERNAME in Environment Variables​

No Figma configuration found in config file​

Mismatch in Figma Ids and Screenshot Viewports in figma config​

Uploading Figma designs failed​

Timeout: Fetching figma results took more than 5 minutes.​

SDK​

contextId and snapshotName are required parameters​

No buildId found for contextId​

Page instance not available​

Getting Additional Help​

Additional Resources​

Test across 3000+ combinations of browsers, real devices & OS.

Help and Support

Do you find this helpful?

Still need help?

Related Articles

Quick Diagnostic Checklist

Troubleshooting by Category

Issue: "Project Not Found" Error

Issue: Credentials Not Working (Hooks)

Issue: CLI Installation and Version Management

Error Message Reference

Authentication and Setup

Authentication failed

SmartUI capabilities are missing in env variables or in driver capabilities

Configuration File

Invalid config; web config must have either customViewports or both browsers and viewports

Invalid config; rejectionThreshold must be greater than approvalThreshold

customViewports is only supported for the exec command. Use browsers and viewports instead.

No URLs found in the specified config file

Web Static Config file not found

Invalid customCSS file type

Builds and Uploads

SmartUI build creation failed

Finalize build failed

Uploading screenshots failed

PDF upload failed

Project ID not found to fetch PDF results

Snapshot processing failed

Local Server and Network

SmartUI server setup failed

No available ports found in range

Invalid port number. Port number must be an integer between 1 and 65535.

Invalid proxy URL

Merging Builds and Branches

Merging two similar build is not possible

Merging two similar branch is not possible

Error: The --source option cannot be empty.

Merging SmartUI build failed

Figma

Missing LT_USERNAME in Environment Variables

No Figma configuration found in config file

Mismatch in Figma Ids and Screenshot Viewports in figma config

Uploading Figma designs failed

Timeout: Fetching figma results took more than 5 minutes.

SDK

contextId and snapshotName are required parameters

No buildId found for contextId

Page instance not available

Getting Additional Help

Additional Resources