Troubleshooting

This guide covers the most common issues you may encounter in RESTK and how to resolve them. For feature-specific troubleshooting, see the dedicated sections linked in each category below.

Requests & Connections

Request Fails with "Could Not Connect"

Causes:

• Target server is down or unreachable
• Incorrect URL or port
• Firewall or proxy blocking the connection
• DNS resolution failure

Solutions:

1. Verify the URL is correct — check for typos, missing port numbers, or wrong protocol (http vs https)
2. Try the URL in a browser to confirm the server is reachable
3. Check if a VPN or proxy is required for the target network
4. For localhost APIs, confirm your local server is running

SSL/TLS Certificate Errors

Causes:

• Self-signed certificate on the target server
• Expired certificate
• Certificate hostname mismatch

Solutions:

• For development servers with self-signed certs, disable SSL verification in the request's Settings tab under Security
• For production APIs, contact the API provider — the certificate issue is on their end
• RESTK uses your operating system's certificate store, so installing the CA certificate at the OS level resolves most trust issues

Timeout Errors

Cause: The server did not respond within the configured timeout period (default: 30 seconds).

Solutions:

• Increase the timeout in the request's Settings tab (Connection, Response, or Total timeout)
• Check if the API endpoint is slow or overloaded
• Verify your internet connection is stable
• For large payloads, the server may need more time to process — consider optimizing the request

Empty Response Body

Cause: The server returned no body, which may be expected behavior.

Check:

• Status code 204 No Content is intentionally empty
• DELETE requests often return no body
• HEAD requests never return a body

If you expected a body, check the API documentation or verify the request parameters are correct.

See also: Viewing Responses — Troubleshooting

---

Variables & Environments

Variables Not Resolving (Shows {{variable_name}} Literally)

Causes:

• No active environment selected
• Variable name is misspelled
• Variable is defined in a different scope (collection vs environment)

Solutions:

1. Check the environment dropdown in the toolbar — make sure an environment is active
2. Hover over the {{variable}} reference to see if RESTK recognizes it (unresolved variables appear in red)
3. Verify the variable exists in the expected scope by opening the environment or collection variables panel
4. Variable names are case-sensitive — {{Base_URL}} and {{base_url}} are different variables

Variable Has Wrong Value

Cause: A higher-priority scope is overriding the expected value.

RESTK resolves variables using this priority order (highest to lowest):

1. Runtime Variables (set by nova.variable.set())
2. Request Variables
3. Folder Variables (walks up the folder chain)
4. Collection Variables
5. Environment Variables

Solution: Hover over the variable reference to see which scope the resolved value comes from. Remove or rename the conflicting variable in the higher-priority scope.

Script-Set Variables Disappearing

Cause: nova.variable.set() is runtime-only — values are not persisted after the session ends.

Solution: Use scope-specific methods for persistence:

// These persist across sessions
nova.environment.set("key", "value");
nova.collectionVariables.set("key", "value");

// This does NOT persist
nova.variable.set("key", "value"); // Runtime only

See also: Variables Guide, Environments

---

Authentication

401 Unauthorized Responses

Causes:

• Token is expired
• Token is missing (auth not configured)
• Wrong auth type selected

Solutions:

1. Check the Auth tab — verify the correct auth type is selected
2. If using Bearer Token, confirm the token value is not empty or expired
3. If using variables (e.g., {{access_token}}), verify the variable resolves to a valid value
4. Check auth inheritance — the request may be set to "Inherit" from a parent that has no auth configured

Auth Header Not Being Sent

Cause: Auth type is set to "None" or "Inherit" with no parent auth.

Solution:

• Open the Auth tab and verify the auth type is not "None"
• If set to "Inherit", check the parent folder and collection for auth configuration
• Check the auto-generated headers panel to see what RESTK is actually sending

See also: Authentication Guide

---

Import & Migration

Import Fails or Produces Empty Collection

Causes:

• File format doesn't match the selected import type
• File is corrupted or contains invalid JSON/YAML
• Unsupported format version (e.g., Postman v2.0 instead of v2.1)

Solutions:

1. Verify the file format — open it in a text editor and check the structure
2. For OpenAPI specs, validate the spec at Swagger Editor before importing
3. Ensure you selected the correct import type (Postman v2.1, OpenAPI 3.x, or cURL)

Imported Scripts Not Working

Cause: Postman uses the pm.* scripting API. RESTK uses the nova.* API.

Solution: RESTK auto-converts Postman scripts by default during import. If auto-conversion was disabled, manually convert:

See also: Import & Export — Troubleshooting, Scripting

Variables Not Resolving After Import

Cause: Environment file was not imported alongside the collection, or the imported environment is not active.

Solution:

1. Import the Postman environment file (.postman_environment.json) separately — drag and drop it into RESTK
2. After import, set the imported environment as active in the toolbar dropdown
3. Check that variable names match between the collection's {{references}} and the environment's keys

---

Sync & Collaboration

Changes Not Syncing to Other Devices

Check:

• Internet connection is active on both devices
• You are signed in with the same account on both devices
• You are in the correct workspace
• Your workspace role allows pushing changes

Solutions:

1. Click the sync icon in the toolbar to force a sync
2. Check the sync status indicator — an orange badge means pending changes, red means error
3. Restart RESTK if sync appears stuck

Cannot See a Teammate's Workspace

Cause: You have not been invited to the workspace.

Solution: Ask a workspace Manager or Owner to send you an invitation. Check your notifications panel for pending invitations.

See also: Sync & Collaboration — Troubleshooting, Roles & Permissions — Troubleshooting

---

Collection Runner

All Requests Failing in Runner

Check:

• Internet connection is active
• Variables resolve correctly (no literal {{unresolved}} in URLs)
• An environment is active if the collection uses environment variables
• The API endpoint is accessible

Runner Is Slow

Causes:

• Large delay configured between requests (sequential mode)
• Low concurrency setting (parallel mode)
• API responses are slow
• Complex scripts executing between requests

Solutions:

• Reduce the delay between requests
• Increase concurrency for parallel mode
• Optimize pre-scripts and post-scripts

See also: Collection Runner — Troubleshooting

---

AI Integration

AI Cannot See My Collection

Cause: Collection has AI sharing disabled.

Solution: Enable Share with AI in collection settings.

AI Actions Not Working

Cause: Approval dialog timed out or was denied.

Solution: Try again and approve the action within 60 seconds. Ensure RESTK is in the foreground when the AI requests approval.

See also: AI Integration — Troubleshooting

---

Application Issues

RESTK Won't Launch

• Ensure macOS 14 or later is installed (RESTK requires macOS 14+)
• Try right-clicking the app and selecting "Open" if macOS blocks it
• Check System Settings > Privacy & Security for any blocked app warnings
• Clear the cache at ~/Library/Caches/com.ai.restk/ and try again

High Memory Usage

Cause: This is unusual for RESTK since it is a native app. Possible causes include very large response bodies loaded in memory or many tabs open simultaneously.

Solutions:

• Close unused tabs
• Clear response history for collections with very large responses
• Restart the app to reclaim memory

App Crashes

Solutions:

1. Update to the latest version of RESTK
2. Restart the app
3. If the crash is reproducible, report it at [email protected] with steps to reproduce

---

Getting More Help

If your issue is not covered here:

• Feature-specific docs — Each feature page has its own troubleshooting section. Browse the sidebar to find the relevant page.
• Email support — Contact [email protected] with a description of the issue and steps to reproduce.

---

Next Steps