Troubleshooting¶

Common issues and solutions when working with REDCap and rcol.

Installation Issues¶

rcol not found after installation¶

Symptom: ModuleNotFoundError: No module named 'rcol'

Solutions:

Ensure you're using the correct Python environment:

# Check which Python is active
which python  # Linux/macOS
where python  # Windows

Reinstall rcol:

uv add rcol
# or
pip install --upgrade rcol

Verify installation:
```
python -c "import rcol; print('OK')"
```

Dependency conflicts¶

Symptom: Error messages about incompatible package versions

Solutions:

Create a fresh virtual environment:
```
uv venv --python 3.11
uv add rcol
```

Or with pip:

python -m venv .venv --clear
.venv\Scripts\activate  # Windows
pip install rcol

API Issues¶

403 Forbidden Error¶

Symptom: {"error": "You do not have permissions to use the API"}

Causes & Solutions:

Cause	Solution
Token not approved	Wait for admin approval
Wrong token	Verify token is copied correctly
Insufficient rights	Request additional API permissions

401 Unauthorized Error¶

Symptom: {"error": "Invalid token"}

Solutions:

Verify your token is correct (no extra spaces)
Check if token was regenerated
Request a new token if necessary

SSL Certificate Error¶

Symptom: SSLCertVerifyError: certificate verify failed

Solutions:

Update certifi package:
```
pip install --upgrade certifi
```
If on a corporate network, you may need to install your organization's CA certificate

Upload Issues¶

Duplicate field names¶

Symptom: {"error": "The field_name column contains duplicate values: record_id"}

Solution:

Remove duplicate record_id when combining instruments:

from rcol.instruments import fal, ehi
import pandas as pd

# Remove record_id from second instrument
ehi_no_id = ehi[ehi["field_name"] != "record_id"]

# Combine
instruments = pd.concat([fal, ehi_no_id], ignore_index=True)

Invalid field type¶

Symptom: {"error": "Invalid field type"}

Solution:

Check that field_type values are valid:

valid_types = [
    "text", "notes", "dropdown", "radio", 
    "checkbox", "yesno", "truefalse", 
    "file", "slider", "calc", "descriptive"
]

invalid = df[~df["field_type"].isin(valid_types)]
if len(invalid) > 0:
    print("Invalid field types found:")
    print(invalid[["field_name", "field_type"]])

Branching logic errors¶

Symptom: Upload succeeds but branching logic doesn't work

Solution:

Verify branching logic syntax:

# Check for common issues
for idx, row in df.iterrows():
    logic = row.get("branching_logic", "")
    if logic:
        # Check for smart quotes
        if '"' in logic or '"' in logic:
            print(f"Smart quotes in {row['field_name']}")

        # Check for missing brackets
        if logic.count('[') != logic.count(']'):
            print(f"Unbalanced brackets in {row['field_name']}")

Survey Issues¶

Survey link not working¶

Checklist:

[ ] Project has surveys enabled
[ ] Instrument is enabled as survey
[ ] Survey status is "Active"
[ ] Link is the correct type (public vs. participant-specific)

Missing required field marker¶

Solution:

In survey settings, enable "Display required field indicator"

Survey displays incorrectly on mobile¶

Solutions:

Use responsive field alignment
Test with REDCap's mobile preview
Avoid very long field labels

Data Issues¶

Exported data has wrong encoding¶

Symptom: Special characters (ä, ö, ü) display incorrectly

Solution:

# When reading exported data
df = pd.read_csv("export.csv", encoding="utf-8-sig")

# When uploading
instruments.to_json(orient="records", force_ascii=False)

Choices not displaying correctly¶

Symptom: Radio/dropdown choices show raw values

Solution:

Verify choice format: value, label | value, label

# Correct format
choices = "1, Yes | 2, No | 3, Maybe"

# Common mistakes
wrong1 = "1,Yes | 2,No"      # Missing space after comma
wrong2 = "1, Yes; 2, No"      # Wrong separator (semicolon)
wrong3 = "Yes | No"           # Missing values

Getting Help¶

If you're still stuck:

Check REDCap documentation: Your institution may have local guides
Contact REDCap admin: For project-specific issues
Open an issue: On the rcol GitHub repository

When reporting issues, include:

Python version (python --version)
rcol version (pip show rcol)
Full error message
Minimal code to reproduce the issue