Skip to main content

​
Development Environment Issues

Symptoms: Build errors, native module compilation failuresSolutions:
  1. Use Git Bash: Always run commands in Git Bash, never cmd or PowerShell 
    # Wrong: Running in cmd/PowerShell
# Right: Use Git Bash for Windows
  2. Install Visual Studio Build Tools:
    • Install Visual Studio Community with “Desktop development with C++”
    • Include “C++ Clang Tools for Windows”
  3. Clean and Rebuild: 
    # If you ran yarn in wrong shell:
rm -rf node_modules
yarn install
  4. Exclude from Windows Defender: Add trezor-suite folder to exclusions for better performance
See the Windows Development Guide for complete setup instructions.
Symptoms: Coin update scripts fail, cointool errorsSolutions:
  1. Create Virtual Environment: 
    python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  2. Install Dependencies: 
    pip install -r submodules/trezor-common/tools/requirements.txt
  3. Update Coins: 
    yarn update-submodules
yarn update-coins
Symptoms: Missing files, outdated dependenciesSolutions:
  1. Update Submodules: 
    git submodule update --init --recursive
  2. Enable Auto-Update (recommended): 
    git config --global submodule.recurse true
  3. Clean Submodules: 
    git submodule foreach --recursive git clean -fd
git submodule update --init --recursive
Symptoms: Dependency resolution errors, network timeoutsSolutions:
  1. Clear Cache: 
    yarn cache clean
rm -rf node_modules
yarn install
  2. Check Node Version: 
    nvm install  # Install version from .nvmrc
nvm use      # Switch to correct version
  3. Network Issues: Use a stable network connection, try again if timeout occurs
Symptoms: Binary files corrupted, large files missingSolutions:
  1. Install Git LFS: 
    git lfs install
  2. Pull LFS Files: 
    git lfs pull
  3. Verify LFS Files: 
    git lfs ls-files

​
Connect Integration Issues

Symptoms: TrezorConnect.init() fails or times outSolutions:
  1. Check Manifest Configuration: 
    TrezorConnect.init({
  manifest: {
    email: '[email protected]',  // Required
    appUrl: 'https://example.com'     // Required
  }
});
  2. Verify Package Import: 
    // Correct imports for v10:
import TrezorConnect from '@trezor/connect-web';
// or
import TrezorConnect from '@trezor/connect-webextension';
  3. Check Console Errors: Open browser DevTools and check for detailed error messages
Symptoms: Device connected but not recognizedSolutions:
  1. Check USB Connection: Try different USB port or cable
  2. Update Browser: Ensure you’re using a supported browser (Chrome, Firefox, Brave)
  3. Bridge Installation (for older browsers):
  4. Linux udev Rules: 
    # Install udev rules
wget https://data.trezor.io/udev/51-trezor.rules
sudo mv 51-trezor.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
Symptoms: API methods fail with error responsesSolutions:
  1. Check Result Object: 
    const result = await TrezorConnect.getAddress({...});

if (!result.success) {
  console.error('Error:', result.payload.error);
  console.error('Code:', result.payload.code);
}
  2. Verify Parameters: Ensure all required parameters are provided
  3. Check Device State: Device must be unlocked and ready
  4. Review Error Codes: See error code documentation for specific issues
Symptoms: “Coin not supported” or similar errorsSolutions:
  1. Check Supported Coins: See Supported Cryptocurrencies
  2. Verify Device Firmware: Some coins require minimum firmware version
  3. Update Connect: Ensure you’re using latest version
  4. Migration Required: EOS and NEM removed in v10, see Migration Guide

​
Suite Application Issues

Symptoms: Application crashes on startup or won’t openSolutions:
  1. Clear Application Cache:
    • macOS: ~/Library/Application Support/Trezor Suite
    • Windows: %APPDATA%/Trezor Suite
    • Linux: ~/.config/trezor-suite
  2. Check Logs:
    • macOS: ~/Library/Logs/Trezor Suite
    • Windows: %APPDATA%/Trezor Suite/logs
    • Linux: ~/.config/trezor-suite/logs
  3. Reinstall Application: Download fresh copy from trezor.io
Symptoms: “Backend offline” or connection errorsSolutions:
  1. Check Internet Connection: Ensure stable internet access
  2. Firewall Settings: Allow Suite through firewall
  3. Try Different Network: Switch from VPN or restrictive network
  4. Backend Status: Check if backend services are operational
Symptoms: Transaction signed but not appearing on blockchainSolutions:
  1. Wait for Confirmation: Network congestion may delay broadcast
  2. Check Transaction ID: Verify on blockchain explorer
  3. Retry Broadcast: Some wallets allow manual rebroadcast
  4. Verify Fee: Low fees may cause delays or rejection

​
Performance Issues

Symptoms: Initial setup takes over 20 minutes, builds over 15 minutesSolutions:
  1. Windows Performance:
    • Use WSL2 for better performance
    • Exclude from Windows Defender
    • Use SSD for project directory
  2. Incremental Builds: Use yarn dev instead of full rebuilds
  3. Parallel Builds: Ensure yarn is using parallel builds
Symptoms: Build process consumes excessive RAMSolutions:
  1. Increase Node Memory: 
    export NODE_OPTIONS="--max-old-space-size=8192"
  2. Close Other Applications: Free up system memory
  3. Use Production Build: Dev builds consume more memory

​
Testing Issues

Symptoms: Tests fail in CI but pass locallySolutions:
  1. Check Network Access: Some tests require network connectivity
  2. Increase Timeout: Adjust timeout values for slower environments
  3. Use Emulator: Set up trezor-user-env for hardware wallet emulation
Symptoms: trezor-user-env fails to startSolutions:
  1. Check Docker: Ensure Docker is running
  2. Port Conflicts: Check if required ports are available
  3. Pull Latest Image: 
    docker pull trezor/trezor-user-env

​
Getting More Help

FAQ

Check frequently asked questions

Best Practices

Learn recommended approaches

GitHub Issues

Report bugs and request features

Trezor Support

Contact official support
Security Issues: For security vulnerabilities, email [email protected] instead of creating public issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us