Troubleshooting

This page covers the most common issues you might encounter while using RTILA X, organized by category. For each issue, you’ll find the symptom, likely cause, and step-by-step solution.

Browser Won’t Launch

Symptom 1: Browser doesn’t open when running a project

Likely Causes:

• No compatible browser is installed.
• The browser path is incorrect.
• The browser is blocked by antivirus software.

Solutions:

1. Check browser installation. Ensure Microsoft Edge, Brave, or Google Chrome is installed. RTILA X requires one of these browsers.
2. Check browser path. Go to Preferences → General → Browser. Verify the browser path is correct. Click “Open Folder” to verify the path exists.
3. Check antivirus. Some antivirus software blocks Playwright from launching browsers. Add an exclusion for RTILA X and Playwright.
4. Try a different browser. Go to Preferences → General → Browser and select a different browser.

Symptom 2: Browser opens but shows a blank page

Likely Causes:

• The target URL is incorrect.
• The page requires JavaScript that is blocked.
• The page requires login.

Solutions:

1. Check the URL. Verify the starting URL in your project settings is correct.
2. Check for login walls. If the page requires login, add login commands before the extraction commands.
3. Check for JavaScript blockers. Some ad blockers or privacy extensions block JavaScript. Disable them in the browser profile.

Symptom 3: Browser crashes immediately after launching

Likely Causes:

• Insufficient system resources.
• Corrupted browser profile.
• Browser version incompatibility.

Solutions:

1. Check system resources. Ensure you have at least 4 GB of free RAM. Close other applications.
2. Clear the browser profile. Delete the profile directory at ~/.rtila-x/profiles/<profile-id>/ and recreate the profile.
3. Update the browser. Ensure your browser is updated to the latest version.
4. Try headless mode. Enable headless mode in project settings to reduce resource usage.

AI Engine Won’t Start

Symptom 1: “Failed to start” error when using Local LLM

Likely Causes:

• Insufficient RAM for the model and context size.
• GPU drivers are outdated.
• The model file is corrupted.

Solutions:

1. Reduce context size. Go to Preferences → AI Assistant → Server Configuration. Reduce the Context Size to 8K or 4K.
2. Reduce GPU Layers. Set GPU Layers to 0 to run on CPU only.
3. Update GPU drivers. If you’re using a GPU, update to the latest drivers.
4. Re-download the model. Delete the model file and let RTILA re-download it.

New in v8.3.2: Error messages now include hardware-specific guidance:

• “Your hardware lacks sufficient RAM/VRAM for the requested context size” → Reduce Context Size or GPU Layers
• “GPU driver may be outdated or incompatible” → Update GPU drivers or set GPU Layers to 0
• “GGUF file may be corrupted or incompatible” → Re-download the model

Symptom 2: Model download fails

Likely Causes:

• No internet connection.
• Disk space is full.
• Hugging Face is temporarily unavailable.

Solutions:

1. Check internet connection. Ensure you have a stable internet connection.
2. Check disk space. Models can be 4–10 GB. Ensure you have sufficient disk space.
3. Retry the download. Hugging Face may be temporarily unavailable. Wait a few minutes and try again.
4. Try a different model. If one model fails, try a different model from the recommended list.

Symptom 3: AI responses are very slow

Likely Causes:

• Model is too large for your hardware.
• Context size is too large.
• GPU is not being used.

Solutions:

1. Use a smaller model. Switch to a 7B model instead of 13B+.
2. Reduce context size. Reduce to 8K or 16K.
3. Check GPU usage. Ensure GPU Layers is set to a value greater than 0 if you have a GPU.
4. Use Q8_0 KV cache. Go to Preferences → AI Assistant → KV Cache. Set KV Cache Type K and V to Q8_0 to reduce memory usage.

Symptom 4: AI generates invalid commands

Likely Causes:

• Model is too small to handle the full command reference.
• Context window is too small.

Solutions:

1. Use a larger model. Use at least a 7B model for reliable command generation.
2. Increase context size. Ensure the context size is at least 32K (the default).
3. Use OpenRouter. Cloud models are generally more reliable for complex command generation.

Symptom 5: “llama-server exited prematurely” error

Likely Causes:

• Out of memory.
• Model file is corrupted.
• GPU driver issue.

Solutions:

1. Check the error message. v8.3.2 includes specific guidance in the error message.
2. Reduce context size. Reduce to 8K or 4K.
3. Set GPU Layers to 0. Run on CPU only.
4. Re-download the model. The model file may be corrupted.
5. Switch to OpenRouter. If local LLM continues to fail, use a cloud provider.

Project Fails to Run

Symptom 1: Project fails with “Element not found” error

Likely Causes:

• The selector doesn’t match any element on the page.
• The page structure has changed.
• The element is inside an iframe.

Solutions:

1. Check the selector. Open the page in your browser and verify the selector matches. Use the Element Picker to regenerate the selector.
2. Check for page changes. The website may have updated its HTML. Re-record or re-select the elements.
3. Check for iframes. If the element is inside an iframe, specify the iframe selector in the command’s iframe parameter.
4. Add a wait command. The element may not be loaded yet. Add a wait_for_selector command before the failing command.

Symptom 2: Project fails with “Timeout” error

Likely Causes:

• The page takes too long to load.
• The navigation timeout is too short.
• The website is slow or unresponsive.

Solutions:

1. Increase the navigation timeout. Go to Project Settings → General → Navigation Timeout. Increase it to 60000 or higher.
2. Add wait commands. Add wait_for_load_state commands after navigation commands.
3. Check the website. The website may be slow or temporarily unavailable.

Symptom 3: Project fails with “Connection refused” error

Likely Causes:

• No internet connection.
• The target website is down.
• A firewall is blocking the connection.

Solutions:

1. Check internet connection. Ensure you have a stable internet connection.
2. Check the website. Open the URL in your browser to verify it’s accessible.
3. Check firewall settings. Ensure your firewall isn’t blocking RTILA X.

Symptom 4: Project fails with “Authentication failed” error

Likely Causes:

• Login credentials are incorrect.
• The login page structure has changed.
• The website requires 2FA.

Solutions:

1. Check credentials. Verify the username and password are correct.
2. Check the login page. The login form structure may have changed. Re-record the login steps.
3. Handle 2FA. If the website requires 2FA, add a request_user_input step to prompt for the 2FA code.

Symptom 5: Project fails with “CAPTCHA detected” error

Likely Causes:

• The website has a CAPTCHA.
• CAPTCHA solving is not enabled.
• The CAPTCHA service is out of balance.

Solutions:

1. Enable CAPTCHA solving. Go to Preferences → Stealth & Proxies. Enable CAPTCHA Solving and enter your 2Captcha API key.
2. Check your balance. Ensure your 2Captcha account has sufficient balance.
3. Enable humanoid behavior. Enable humanoid behavior to reduce the chance of CAPTCHAs appearing.

Data Not Extracted

Symptom 1: No data is extracted

Likely Causes:

• The item selector doesn’t match any elements.
• The dataset is not configured correctly.
• The page requires JavaScript to render content.

Solutions:

1. Check the item selector. Use the Element Picker to verify the selector matches elements on the page.
2. Check the dataset configuration. Ensure the dataset has at least one property configured.
3. Wait for content to load. Add a wait_for_selector command before the extract_data command.
4. Check for JavaScript rendering. Some pages require JavaScript to render content. Ensure JavaScript is enabled in the browser profile.

Symptom 2: Data is extracted but values are empty

Likely Causes:

• The property selectors don’t match elements.
• The elements are empty on the page.
• The selectors are relative to the wrong parent.

Solutions:

1. Check property selectors. Verify each property selector matches elements within the item container.
2. Check the page content. Open the page and verify the elements have content.
3. Check selector context. Property selectors are relative to the item selector. Ensure they’re correct relative to the item container.

Symptom 3: Data is extracted but has extra whitespace

Likely Causes:

• The page has extra whitespace around text.
• The trim transformation is not applied.

Solutions:

1. Add trim transformation. Add a trim transformation to the property in the dataset.
2. Check the page source. Open the page source and check for extra whitespace.

Symptom 4: Data is extracted but values are wrong

Likely Causes:

• The property selectors match the wrong elements.
• The page structure is different from expected.

Solutions:

1. Check property selectors. Verify each property selector matches the correct element.
2. Use the Element Picker. Re-select the elements using the Element Picker.
3. Check the page structure. The page structure may be different from what you expected.

Triggers Not Running

Symptom 1: Triggers don’t fire after a project run

Likely Causes:

• The project run didn’t complete successfully.
• Triggers are not configured for the project.
• The project was stopped manually.

Solutions:

1. Check the run status. Triggers only fire when the run status is completed or failed. If the run was stopped or killed, triggers won’t fire.
2. Check trigger configuration. Go to the project’s Triggers tab and verify triggers are configured.
3. Check the execution logs. Look for trigger execution errors in the logs.

Symptom 2: Trigger fails with “Connection refused” error

Likely Causes:

• The destination server is unreachable.
• The API endpoint is incorrect.
• Network connectivity issue.

Solutions:

1. Check the destination. Verify the API endpoint, database, or cloud storage destination is accessible.
2. Check credentials. Verify API keys, database credentials, or cloud storage credentials are correct.
3. Check network connectivity. Ensure you have a stable internet connection.

Symptom 3: Trigger fails with “Authentication failed” error

Likely Causes:

• API key or credentials are incorrect.
• The API key has expired.
• Insufficient permissions.

Solutions:

1. Check credentials. Verify the API key, database credentials, or cloud storage credentials are correct.
2. Check permissions. Ensure the credentials have the necessary permissions.
3. Regenerate credentials. If the credentials have expired, regenerate them.

Symptom 4: Trigger runs but data is not delivered

Likely Causes:

• The data is empty.
• The destination format is incorrect.
• The destination rejected the data.

Solutions:

1. Check the data. Verify the data was extracted correctly.
2. Check the destination format. Ensure the data format matches what the destination expects.
3. Check the execution logs. Look for error messages in the trigger execution logs.

Log File Locations

Log Type	Location	Description
Application logs	~/.rtila-x/logs/	General application logs
Execution logs	View in Execution Logs page	Detailed logs from automation runs
Database logs	~/.rtila-x/database/data/	PocketBase database logs
Model logs	~/.rtila-x/models/	Local AI model files and logs

Getting Help

Resource	URL	Description
Support Forum	rtila.net	Community support forum
Documentation	This documentation	Complete RTILA X documentation
Email Support	support@rtila.com	Email support for paid plans
Discord	Community Discord	Real-time community support

Resetting the Application

If RTILA X is in a broken state and you can’t fix the issue, you can reset the application:

Soft Reset (Preserve Data)

1. Close RTILA X completely.
2. Navigate to ~/.rtila-x/.
3. Delete the profiles/ directory to reset browser profiles.
4. Restart RTILA X.

Full Reset (Delete All Data)

Warning: This deletes ALL data including projects, sessions, logs, and settings.

1. Close RTILA X completely.
2. Navigate to ~/.rtila-x/.
3. Delete the entire ~/.rtila-x/ directory.
4. Restart RTILA X. It will re-initialize from scratch.

Reset License Only

1. Go to Preferences → General → Administration → Open Administration Tools.
2. Go to the Advanced tab.
3. Click “Reset License Data”.
4. Confirm the reset.
5. You’ll need to re-enter your license key.