Troubleshooting

This page covers common problems you might encounter and how to solve them.

Authentication Errors

Missing RECURSE_PAT Environment Variable

Error Message: RECURSE_PAT environment variable not set

Cause: The required Personal Access Token environment variable is not configured. Solution:

Create a .env file

Create a .env file in the project root directory:

touch .env

Add your token

Add your Personal Access Token to the file:

RECURSE_PAT=your_token_here

Verify the file

Ensure the .env file is in the same directory where you run cargo run:

ls -la .env
cat .env  # Should show RECURSE_PAT=...

Alternative: Export directly

If you don’t want to use a .env file:

# Unix/Linux/macOS
export RECURSE_PAT=your_token_here
cargo run

# Or inline
RECURSE_PAT=your_token_here cargo run

# Windows PowerShell
$env:RECURSE_PAT="your_token_here"
cargo run

# Windows CMD
set RECURSE_PAT=your_token_here
cargo run

Authentication Failed (401)

Error Message: Authentication failedHTTP Status: 401 Unauthorized

Cause: The Personal Access Token is invalid, expired, or malformed. Common Reasons:

Token was copied incorrectly (extra spaces, missing characters)
Token has been revoked or expired
Token was created for a different environment

Solution:

Verify token format

Check that your token has no extra spaces or newlines:

# Print the token to verify
echo "$RECURSE_PAT"

# Should be a single line with no spaces at start/end

Generate new token

Create a fresh Personal Access Token:

Log in to www.recurse.com
Navigate to Settings → Personal Access Tokens
Create a new token with description “VCF Generator”
Copy the token immediately

Update environment variable

Replace the old token in your .env file:

RECURSE_PAT=new_token_here

Test authentication

Run the application to verify:

cargo run

You can also test authentication using basic auth to create a new token programmatically (see rc_api::create_token()).

API Errors

Resource Not Found (404)

Error Message: Resource not foundHTTP Status: 404 Not Found

Cause: The requested profile, batch, or resource doesn’t exist or you don’t have access to it. Common Scenarios:

Profile not found

// Error: Profile ID doesn't exist
let profile = client.get_profile_by_id(999999)?;

// Error: Email not in system
let profile = client.get_profile_by_email("[email protected]")?;

Solution: Verify the ID or email exists by searching first:

let results = client.search_profiles(ProfileSearchParams {
    query: Some("[email protected]".to_string()),
    ..Default::default()
})?;

if results.is_empty() {
    println!("No profile found for that email");
}

Batch not found

// Error: Invalid batch ID
let batch = client.get_batch(12345)?;

Solution: List all batches first:

let batches = client.list_batches()?;
for batch in batches {
    println!("Batch {}: {}", batch.id, batch.name);
}

Bad Request (400)

Error Message: Bad request: ...HTTP Status: 400 Bad Request

Cause: Invalid parameters or malformed request data. Common Issues:

Invalid query parameters

// Error: Invalid limit value
let profiles = client.search_profiles(ProfileSearchParams {
    limit: Some(0),  // Must be > 0
    ..Default::default()
})?;

Solution: Use valid parameter values:

let profiles = client.search_profiles(ProfileSearchParams {
    limit: Some(50),  // Valid range: 1-100
    offset: Some(0),
    ..Default::default()
})?;

Invalid date format

// Error: Wrong date format
let visit = client.get_hub_visit(123, "2024-13-01".parse()?)?;

Solution: Use proper NaiveDate parsing:

use chrono::NaiveDate;

let date = NaiveDate::from_ymd_opt(2024, 12, 1)
    .expect("Invalid date");
let visit = client.get_hub_visit(123, date)?;

API Error (Other Status Codes)

Error Message: API error: HTTP {status}

Cause: Unexpected server error or rate limiting. Common Status Codes:

Status	Meaning	Common Cause
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issue
503	Service Unavailable	Maintenance or downtime

Solution:

Check for rate limiting

If you see 429 errors, add delays between requests:

use std::time::Duration;
use std::thread;

for profile_id in profile_ids {
    match client.get_profile_by_id(profile_id) {
        Ok(profile) => { /* ... */ },
        Err(e) => {
            eprintln!("Error: {}", e);
            thread::sleep(Duration::from_secs(5));
        }
    }
}

Check RC status

Visit the Recurse Center website to check if there’s a known outage.

Retry with exponential backoff

let mut retry_delay = Duration::from_secs(1);
let max_retries = 5;

for attempt in 0..max_retries {
    match client.get_my_profile() {
        Ok(profile) => return Ok(profile),
        Err(e) if attempt < max_retries - 1 => {
            eprintln!("Attempt {} failed: {}", attempt + 1, e);
            thread::sleep(retry_delay);
            retry_delay *= 2; // Exponential backoff
        }
        Err(e) => return Err(e),
    }
}

Network Errors

HTTP Request Failed

Error Message: HTTP request failed: {details}

Cause: Network connectivity issues or DNS resolution failures. Common Scenarios:

Connection timeout

Error: HTTP request failed: operation timed outSolution:

Check your internet connection

Verify you can reach www.recurse.com:

ping www.recurse.com
curl https://www.recurse.com/api/v1

Check if you’re behind a proxy or firewall
Try again later if the RC servers are experiencing issues

DNS resolution failed

Error: HTTP request failed: failed to lookup address informationSolution:

Check your DNS settings
Try using a different DNS server (e.g., 8.8.8.8)
Verify /etc/hosts doesn’t have incorrect entries

Flush your DNS cache:

# macOS
sudo dscacheutil -flushcache

# Linux
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns

SSL/TLS certificate errors

Error: HTTP request failed: certificate verify failedSolution:

Update your system’s CA certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS (via Homebrew)
brew install ca-certificates

Check your system clock is correct (TLS certs are time-sensitive)
If behind a corporate proxy, you may need to add custom CA certificates

JSON Deserialization Errors

Failed to Deserialize Response

Error Message: JSON deserialization failed: {details}

Cause: The API returned unexpected data that doesn’t match the expected structure. Debugging: When deserialization fails, the error handler prints the raw response:

Failed to deserialize response. Error: missing field `email`
Response body:
{"id": 123, "name": "Test User"}

Common Causes:

API schema changed

The Recurse Center API may have updated its schema.Solution:

Check if there’s a newer version of this tool
Report the issue with the error details
The response body in the error message shows what the API actually returned

Using deprecated endpoint

You’re using a deprecated API method.Solution: Replace deprecated methods:

// DON'T use deprecated methods
let person = client.get_person_by_id(123)?;  // Deprecated

// DO use current methods
let profile = client.get_profile_by_id(123)?;  // Current

Partial response

Some optional fields might be unexpectedly null.Solution: Most fields in the data structures are already Option<T>, but if you encounter this:

Check the raw response in the error message
Report the issue if a required field is actually optional
Use #[serde(default)] annotation if contributing a fix

VCF File Issues

Unable to Create Output File

Error Message: Failed to create output file

Cause: Permission denied or invalid output path. Solution:

Check permissions

Ensure you have write permissions in the current directory:

# Check current directory permissions
ls -ld .

# Try creating a test file
touch test.txt && rm test.txt

Use absolute path

Specify a full path where you have write access:

let output_path = "/home/user/Documents/recursers.vcf";

Check disk space

Verify you have enough disk space:

df -h .

The VCF file can be several MB (typically 5-10 MB for all Recursers).

VCF Import Issues

Contacts not importing

Problem: VCF file is created but contacts don’t import into your contacts app.Solution:

Verify the file is valid VCF format:

head -20 recursers.vcf
# Should show BEGIN:VCARD / VERSION:3.0 / etc.

Try a different contacts app (some are more forgiving of format variations)
Check the app’s import logs for specific errors

Photos not appearing

Problem: Contacts import but photos are missing.Causes:

Profile has no photo (image path contains “missing”)
Photo download failed during generation
Contact app doesn’t support embedded photos

Solution:

Check the terminal output for download errors
Note that not all Recursers have profile photos
Some contacts apps require re-syncing to show photos

Duplicate contacts

Problem: Importing creates duplicate entries.Solution:

Most contact apps can merge duplicates automatically
Use the UID field to identify duplicates (format: recurser-{id})
Delete the old import before re-importing

Special characters corrupted

Problem: Names or fields with special characters display incorrectly.Solution:

Verify the VCF file is UTF-8 encoded:

file recursers.vcf
# Should show: UTF-8 Unicode text

If using Windows, ensure your contacts app supports UTF-8
Try opening the VCF in a text editor to verify the data

Build and Runtime Errors

Failed to Create API Client

Error Message: Failed to create API client

Cause: Error initializing the HTTP client. Solution:

// Check what the actual error is
match RcApiClient::new(token) {
    Ok(client) => { /* ... */ },
    Err(e) => eprintln!("Client creation failed: {:?}", e),
}

This is usually caused by:

TLS initialization failure (missing OpenSSL libraries)
System configuration issues

Fix: Install required dependencies:

# Ubuntu/Debian
sudo apt-get install libssl-dev pkg-config

# macOS
brew install openssl

# Fedora/RHEL
sudo dnf install openssl-devel

Then rebuild:

cargo clean
cargo build --release

Compilation Errors

Missing dependencies

Error: error: failed to run custom build command for 'openssl-sys'Solution: Install OpenSSL development libraries (see above).

Rust version too old

Error: error: package requires rustc 1.70.0 or newerSolution: Update Rust:

rustup update stable

Getting Help

If you encounter an issue not covered here:

Check the error message carefully - Most errors include helpful context
Enable debug logging - Set RUST_LOG=debug to see more details:
```
RUST_LOG=debug cargo run
```
Check the raw API response - Deserialization errors print the actual JSON received
Verify your environment - Ensure RECURSE_PAT is set and valid
Search existing issues - Check if others have encountered the same problem
Report the issue - Include:
- Full error message
- Operating system and Rust version
- Steps to reproduce
- Relevant log output (with sensitive data removed)

Get Started

Guides

API Client

Reference

Authentication Errors

Missing RECURSE_PAT Environment Variable

Authentication Failed (401)

API Errors

Resource Not Found (404)

Bad Request (400)

API Error (Other Status Codes)

Network Errors

HTTP Request Failed

JSON Deserialization Errors

Failed to Deserialize Response

VCF File Issues

Unable to Create Output File

VCF Import Issues

Build and Runtime Errors

Failed to Create API Client

Compilation Errors

Getting Help

Build docs developers (and LLMs) love

Get Started

Guides

API Client

Reference

​Authentication Errors

​Missing RECURSE_PAT Environment Variable

​Authentication Failed (401)

​API Errors

​Resource Not Found (404)

​Bad Request (400)

​API Error (Other Status Codes)

​Network Errors

​HTTP Request Failed

​JSON Deserialization Errors

​Failed to Deserialize Response

​VCF File Issues

​Unable to Create Output File

​VCF Import Issues

​Build and Runtime Errors

​Failed to Create API Client

​Compilation Errors

​Getting Help

Build docs developers (and LLMs) love

Authentication Errors

Missing RECURSE_PAT Environment Variable

Authentication Failed (401)

API Errors

Resource Not Found (404)

Bad Request (400)

API Error (Other Status Codes)

Network Errors

HTTP Request Failed

JSON Deserialization Errors

Failed to Deserialize Response

VCF File Issues

Unable to Create Output File

VCF Import Issues

Build and Runtime Errors

Failed to Create API Client

Compilation Errors

Getting Help