Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• main.py
• totally_reset_cursor.py
• config.py
• reset_machine_manual.py
• locales/en.json
• scripts/install.sh

This document provides guidance for diagnosing and resolving common issues encountered while using the cursor-free-vip tool. It covers problems related to configuration, path detection, script execution, and system permissions. For unresolved issues, users are encouraged to create an issue on the GitHub Issue Tracker.

Sources: locales/en.json:302-302

Configuration and Path Issues

Problems often arise from incorrect or missing configuration files and the tool's inability to locate the Cursor application. The tool relies on a central config.ini file and specific directory structures.

Configuration File (config.ini)

The tool automatically creates a config.ini file to store paths and settings. If this process fails, many features will not work correctly.

Default Location:
The configuration directory is created at ~/.cursor-free-vip within the user's documents folder.

Operating System	Default Documents Path	Config Directory
Windows	%USERPROFILE%\Documents	%USERPROFILE%\Documents\.cursor-free-vip
macOS	~/Documents	~/Documents/.cursor-free-vip
Linux	~/Documents	~/Documents/.cursor-free-vip

Sources: config.py:25-34, totally_reset_cursor.py:27-42

If the documents path cannot be determined, the tool falls back to using the current working directory or a temporary directory.

Sources: config.py:28-31, config.py:42-49

Common Configuration Errors:

Error Message	Cause	Solution
Config File Not Found	The config.ini file is missing and could not be created.	Ensure you have write permissions in your Documents folder or the script's directory.
Cannot Read or Write Config File	The script lacks the necessary permissions to access config.ini.	Run the script with administrator/sudo privileges or adjust file permissions (chmod).
Neither Cursor nor Cursor directory found	The script cannot find the Cursor application's configuration directory to set default paths.	Ensure Cursor is installed and has been run at least once to create its configuration files.
Permission denied: {storage_path}	On Linux, the script cannot access Cursor's storage.json file due to ownership issues, especially when run with sudo.	Change the ownership of the specified file to your user: chown user:group {storage_path}.

Sources: locales/en.json:339-340, locales/en.json:402-403, locales/en.json:410-411, config.py:228-243

The diagram below illustrates the configuration setup process, highlighting potential failure points.

Sources: config.py:23-195

Cursor Path Detection

The tool needs to find the Cursor application to modify its files. It uses a combination of default paths and paths stored in config.ini.

Path Detection Logic:

1. The script determines the operating system (Windows, macOS, Linux).
2. It reads the cursor_path from the corresponding section in config.ini.
3. If the configured path does not exist (especially on Linux), it iterates through a list of common default installation directories.
4. On Linux, it also searches for AppImage extractions (squashfs-root).
5. If a valid path is found, it is used and updated in config.ini. If not, an error is raised.

Sources: totally_reset_cursor.py:45-163, reset_machine_manual.py:45-163

Common Path Errors:

Error Message	Cause	Solution
Package.json Not Found	The cursor_path in config.ini is incorrect, or the Cursor installation is corrupt.	Manually edit config.ini to point to the correct Cursor .../resources/app directory.
Linux Path Not Found	The script could not find the Cursor installation in any of the default Linux paths.	Ensure Cursor is installed in a standard location (/opt, /usr/share, ~/.local/share) or update config.ini with the correct path.
Unsupported OS	The script is being run on an operating system other than Windows, macOS, or Linux.	This tool is only supported on Windows, macOS, and Linux.

Sources: locales/en.json:101, locales/en.json:83, locales/en.json:161

Reset and Patching Failures

The "Totally Reset" and "Reset Machine ID" features perform sensitive operations that can fail due to permissions or file modifications.

"Totally Reset" Process

This feature performs a deep clean of Cursor settings and trial-related data.

The flow of the "Totally Reset" process is as follows:

Sources: totally_reset_cursor.py, locales/en.json:278-337

Common Reset Errors:

Error Message	Cause	Solution
Permission Error: {error}	The script lacks permissions to modify system-level identifiers (e.g., Windows Registry, /etc/machine-id).	Run the script with administrator or sudo privileges.
SQLite Database Update Failed	The state.vscdb file is locked, corrupt, or the script lacks write permissions.	Close the Cursor application completely before running the script. Check file permissions.
Modify File Failed: {error}	The script could not patch JavaScript files (main.js, workbench.desktop.main.js) due to permissions or unexpected file content.	Ensure you have write permissions for the Cursor application files. If the file content has changed significantly in a new Cursor update, the patch may fail.
Cursor Version Too Low	The installed Cursor version is older than 0.45.0, which is required for certain patches.	The getMachineId patch is skipped for older versions. The rest of the reset should still function.

Sources: locales/en.json:73, locales/en.json:79, locales/en.json:104, locales/en.json:102

JavaScript Patching

The tool modifies workbench.desktop.main.js to bypass token limits and change UI elements, and out/main.js to patch the getMachineId function. This is done using string replacement.

• Token Limit Bypass: The function getEffectiveTokenLimit is modified to always return a large number (e.g., 9,000,000).
• UI Changes: The "Upgrade to Pro" button is replaced with a link to the project's GitHub repository.

If a Cursor update changes the structure of these JavaScript files, the string replacement patterns may no longer match, causing the patch to fail.

Sources: bypass_token_limit.py:91-112, reset_machine_manual.py:328-356

Installation and Updates

The install.sh script handles downloading and running the pre-compiled binary for Linux and macOS.

Common Installation/Update Errors:

Error Message	Cause	Solution
Cannot get latest version information	Network issue or GitHub API is down/rate-limited.	Check your internet connection and try again later.
Download link does not exist	The binary for your specific OS and architecture was not found in the GitHub release.	Check the releases page to see if a binary is available for your system. The script may fall back to a generic OS binary (e.g., mac instead of mac_arm64).
Downloaded file is too small	The download failed and resulted in an error page (e.g., 404) being saved instead of the binary.	Verify the download URL is correct and that the release asset exists.
GitHub API rate limit exceeded	Too many requests have been made to the GitHub API from your IP address.	The update check will be skipped. You can try again later or update manually.

Sources: scripts/install.sh:41-44, scripts/install.sh:101-125, scripts/install.sh:135-143, locales/en.json:258

The main application also includes an update checker that can be disabled in config.ini.

# From config.py
'Utils': {
    'enabled_update_check': 'True',
    'enabled_force_update': 'False',
    # ...
}

Sources: config.py:99-103

If enabled_update_check is True, the script will contact the GitHub API to check for new versions upon startup.

Sources: main.py:644-645

Summary

Most issues with cursor-free-vip stem from three main areas: permissions, incorrect paths, and breaking changes in new Cursor versions.

1. Permissions: Always try running the script with elevated privileges (Administrator/sudo) if you encounter errors related to file access, especially during reset operations.
2. Paths: If the script cannot find your Cursor installation, ensure it's in a standard location or manually update the cursor_path in your config.ini file.
3. Updates: If a feature like patching stops working after a Cursor update, it's likely because the target files have changed. Check the project's GitHub repository for updates to the tool itself.

By systematically checking these areas, most common problems can be resolved.