Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Upstox TOTP SDK.

Quick Diagnosis

Environment Check

First, always check your environment configuration:

# Use the CLI to check configuration
upstox_cli check-env

# Or programmatically
from upstox_totp import UpstoxTOTP, ConfigurationError

try:
    upx = UpstoxTOTP()
    print("✅ Configuration is valid")
except ConfigurationError as e:
    print(f"❌ Configuration error: {e}")

Debug Mode

Enable debug mode for detailed error information:

from upstox_totp import UpstoxTOTP

# Enable debug logging
upx = UpstoxTOTP(debug=True)

# Or via environment variable
export UPSTOX_DEBUG=true
upstox_cli generate-token

Common Issues

Configuration Errors

Missing Environment Variables

Error: .. code-block:: text

ConfigurationError: Missing required environment variables: UPSTOX_USERNAME, UPSTOX_PASSWORD

Solution:

# Check which variables are set
env | grep UPSTOX

# Set missing variables
export UPSTOX_USERNAME=9876543210
export UPSTOX_PASSWORD=your-password
# ... other variables

# Or create .env file
cat > .env << EOF
UPSTOX_USERNAME=9876543210
UPSTOX_PASSWORD=your-password
UPSTOX_PIN_CODE=1234
UPSTOX_TOTP_SECRET=JBSWY3DPEHPK3PXP
UPSTOX_CLIENT_ID=your-client-id
UPSTOX_CLIENT_SECRET=your-client-secret
UPSTOX_REDIRECT_URI=https://your-app.com/callback
EOF

Invalid Username Format

Error: .. code-block:: text

ValidationError: Username must be exactly 10 digits

Solution:

# Use your 10-digit mobile number (without country code)
# Wrong: +919876543210, 919876543210
# Right: 9876543210
export UPSTOX_USERNAME=9876543210

Invalid TOTP Secret

Error: .. code-block:: text

ValidationError: Invalid TOTP secret format

Solution:

# Ensure TOTP secret is base32 encoded without spaces
# Wrong: "JBSW Y3DP EHPK 3PXP"
# Right: "JBSWY3DPEHPK3PXP"
export UPSTOX_TOTP_SECRET=JBSWY3DPEHPK3PXP

# Test TOTP generation
python -c "
import pyotp
totp = pyotp.TOTP('JBSWY3DPEHPK3PXP')
print(f'TOTP: {totp.now()}')
"

Authentication Errors

Invalid Credentials

Error: .. code-block:: text

Token generation failed: Invalid credentials provided

Solutions:

Verify Username:

# Must be 10-digit mobile number
# Check in Upstox app: Profile → Settings → Personal Details
echo $UPSTOX_USERNAME

Verify Password:

# Try logging into Upstox web platform manually
# If login fails, reset password

Verify PIN:

# Usually 4-6 digits
# Check in Upstox app: Profile → Settings → Security

TOTP Validation Failed

Error: .. code-block:: text

TOTP validation failed

Solutions:

Check TOTP Secret:

import pyotp

# Test TOTP generation
secret = "YOUR_TOTP_SECRET"
totp = pyotp.TOTP(secret)
current_code = totp.now()
print(f"Generated TOTP: {current_code}")

# Compare with your authenticator app

Check System Time:

# TOTP is time-sensitive
# Ensure system time is accurate
date

# Sync time (Linux)
sudo ntpdate -s time.nist.gov

# Sync time (macOS)
sudo sntp -sS time.apple.com

Try Different TOTP Window:

import pyotp
import time

secret = "YOUR_TOTP_SECRET"
totp = pyotp.TOTP(secret)

# Try current and next window
for i in range(3):
    code = totp.at(time.time() + (i * 30))
    print(f"TOTP window {i}: {code}")

OAuth Errors

Invalid Client ID/Secret

Error: .. code-block:: text

OAuth error: invalid_client

Solutions:

Verify Client Credentials:

# Check Upstox Developer Console
# https://developer.upstox.com/
echo "Client ID: $UPSTOX_CLIENT_ID"
echo "Client Secret: $UPSTOX_CLIENT_SECRET"

Check App Status:
- Login to Upstox Developer Console
- Verify app is approved and active
- Check API limits and restrictions

Redirect URI Mismatch

Error: .. code-block:: text

OAuth error: redirect_uri_mismatch

Solution:

# Redirect URI must exactly match app settings
# Check in Upstox Developer Console → Your App → Settings

# Common mistakes:
# Wrong: http://localhost:8080 (missing slash)
# Right: http://localhost:8080/

# Wrong: https://myapp.com/callback/ (extra slash)
# Right: https://myapp.com/callback

export UPSTOX_REDIRECT_URI=https://your-app.com/callback

Network Errors

Connection Timeout

Error: .. code-block:: text

requests.exceptions.ConnectTimeout: HTTPSConnectionPool

Solutions:

Check Internet Connection:

# Test connectivity
ping api.upstox.com
curl -I https://api.upstox.com

Configure Proxy:

from upstox_totp import UpstoxTOTP

upx = UpstoxTOTP()
upx.session.proxies = {
    'http': 'http://proxy.company.com:8080',
    'https': 'https://proxy.company.com:8080'
}

Increase Timeout:

from upstox_totp import UpstoxTOTP

upx = UpstoxTOTP()
upx.session.timeout = (30, 60)  # (connect, read) timeout

SSL Certificate Errors

Error: .. code-block:: text

requests.exceptions.SSLError: certificate verify failed

Solutions:

Update Certificates:

# Update certificates
pip install --upgrade certifi

# Or system-wide (Ubuntu)
sudo apt-get update && sudo apt-get install ca-certificates

Check System Time:
```
# Ensure system time is correct
date
```

Rate Limiting

Error: .. code-block:: text

HTTP 429: Too Many Requests

Solution:

import time
from upstox_totp import UpstoxTOTP

def get_token_with_backoff(max_retries=3):
    for attempt in range(max_retries):
        try:
            upx = UpstoxTOTP()
            response = upx.app_token.get_access_token()

            if response.success:
                return response.data.access_token

        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                delay = 2 ** attempt  # Exponential backoff
                print(f"Rate limited, waiting {delay} seconds...")
                time.sleep(delay)
            else:
                raise

Installation Issues

Package Not Found

Error: .. code-block:: text

No module named ‘upstox_totp’

Solutions:

# Check if package is installed
pip list | grep upstox

# Install package
pip install upstox-totp

# Check Python path
python -c "import sys; print(sys.path)"

# Use virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows
pip install upstox-totp

Permission Denied

Error: .. code-block:: text

PermissionError: [Errno 13] Permission denied

Solutions:

# Install for user only
pip install --user upstox-totp

# Or use virtual environment
python -m venv venv
source venv/bin/activate
pip install upstox-totp

CLI Command Not Found

Error: .. code-block:: text

upstox_cli: command not found

Solutions:

# Check if command is in PATH
which upstox_cli

# Find installation location
pip show upstox-totp

# Use full path
python -m upstox_totp.cli check-env

# Add to PATH
export PATH=$PATH:/path/to/python/scripts

Token Issues

Token Expires Quickly

Issue: Token seems to expire faster than expected

Solution:

import jwt
from datetime import datetime

def check_token_expiry(token):
    # Decode token to check expiry
    decoded = jwt.decode(token, options={"verify_signature": False})

    if 'exp' in decoded:
        exp_time = datetime.fromtimestamp(decoded['exp'])
        now = datetime.now()

        print(f"Token expires at: {exp_time}")
        print(f"Current time: {now}")
        print(f"Time remaining: {exp_time - now}")

# Check your token
check_token_expiry(your_token)

Invalid Token Format

Error: .. code-block:: text

Invalid token format

Solution:

from upstox_totp import UpstoxTOTP

upx = UpstoxTOTP()
response = upx.app_token.get_access_token()

if response.success and response.data:
    token = response.data.access_token

    # Verify token format
    if token.startswith('eyJ'):
        print("✅ Valid JWT token format")
    else:
        print("❌ Invalid token format")

    # Check token length
    if len(token) > 100:
        print("✅ Token has reasonable length")
    else:
        print("⚠️ Token seems too short")

Platform-Specific Issues

Windows Issues

Path Separators

import os
from upstox_totp import UpstoxTOTP

# Use os.path.join for cross-platform paths
env_file = os.path.join("config", ".env")
upx = UpstoxTOTP.from_env_file(env_file)

Environment Variables

REM Set environment variables in Windows
set UPSTOX_USERNAME=9876543210
set UPSTOX_PASSWORD=your-password

REM Or permanently
setx UPSTOX_USERNAME "9876543210"

macOS Issues

Certificate Issues

# Update certificates on macOS
/Applications/Python\ 3.x/Install\ Certificates.command

# Or install certificates manually
pip install --upgrade certifi

Linux Issues

SSL Context Issues

# Update CA certificates
sudo apt-get update
sudo apt-get install ca-certificates

# Or for CentOS/RHEL
sudo yum update ca-certificates

Docker Issues

Environment Variables

# Pass environment variables to container
FROM python:3.12

# Install package
RUN pip install upstox-totp

# Use .env file
COPY .env /app/.env
WORKDIR /app

# Run with environment file
docker run --env-file .env your-image

Network Issues

# Add DNS configuration if needed
FROM python:3.12

RUN echo "nameserver 8.8.8.8" > /etc/resolv.conf

Advanced Debugging

Enable All Logging

import logging
from upstox_totp import UpstoxTOTP

# Enable all debug logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Enable HTTP debugging
import urllib3
urllib3.disable_warnings()

# Enable requests debugging
import http.client as http_client
http_client.HTTPConnection.debuglevel = 1

upx = UpstoxTOTP(debug=True)

Network Traffic Analysis

from upstox_totp import UpstoxTOTP
import requests

# Create session with event hooks
class DebuggingUpstoxTOTP(UpstoxTOTP):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        # Add request/response hooks
        self.session.hooks['response'].append(self.log_response)

    def log_response(self, response, *args, **kwargs):
        print(f"Request: {response.request.method} {response.request.url}")
        print(f"Status: {response.status_code}")
        print(f"Headers: {dict(response.headers)}")

        if response.status_code >= 400:
            print(f"Error response: {response.text}")

# Usage
upx = DebuggingUpstoxTOTP(debug=True)

Memory and Performance Issues

import tracemalloc
import time
from upstox_totp import UpstoxTOTP

def profile_memory_usage():
    tracemalloc.start()

    # Measure memory before
    snapshot1 = tracemalloc.take_snapshot()

    # Generate token
    upx = UpstoxTOTP()
    response = upx.app_token.get_access_token()

    # Measure memory after
    snapshot2 = tracemalloc.take_snapshot()

    # Compare
    top_stats = snapshot2.compare_to(snapshot1, 'lineno')

    print("Memory usage:")
    for stat in top_stats[:10]:
        print(stat)

profile_memory_usage()

Testing Configuration

Configuration Validation Script

#!/usr/bin/env python3
"""
Comprehensive configuration validation script
"""

import os
import sys
from upstox_totp import UpstoxTOTP, ConfigurationError, ValidationError

def validate_environment():
    """Validate environment configuration."""
    print("🔍 Validating Upstox TOTP configuration...\n")

    # Check required environment variables
    required_vars = [
        'UPSTOX_USERNAME',
        'UPSTOX_PASSWORD',
        'UPSTOX_PIN_CODE',
        'UPSTOX_TOTP_SECRET',
        'UPSTOX_CLIENT_ID',
        'UPSTOX_CLIENT_SECRET',
        'UPSTOX_REDIRECT_URI'
    ]

    print("📋 Environment Variables:")
    missing_vars = []
    for var in required_vars:
        value = os.getenv(var)
        if value:
            if 'PASSWORD' in var or 'SECRET' in var:
                print(f"  ✅ {var}: ******** (length: {len(value)})")
            else:
                masked_value = value[:4] + '*' * (len(value) - 4) if len(value) > 4 else '****'
                print(f"  ✅ {var}: {masked_value}")
        else:
            print(f"  ❌ {var}: Not set")
            missing_vars.append(var)

    if missing_vars:
        print(f"\n❌ Missing variables: {', '.join(missing_vars)}")
        return False

    # Test TOTP generation
    print("\n🔐 Testing TOTP generation:")
    try:
        import pyotp
        secret = os.getenv('UPSTOX_TOTP_SECRET')
        totp = pyotp.TOTP(secret)
        code = totp.now()
        print(f"  ✅ TOTP generated: {code}")
    except Exception as e:
        print(f"  ❌ TOTP generation failed: {e}")
        return False

    # Test client initialization
    print("\n🚀 Testing client initialization:")
    try:
        upx = UpstoxTOTP()
        print("  ✅ Client initialized successfully")
    except ConfigurationError as e:
        print(f"  ❌ Configuration error: {e}")
        return False
    except ValidationError as e:
        print(f"  ❌ Validation error: {e}")
        return False
    except Exception as e:
        print(f"  ❌ Unexpected error: {e}")
        return False

    print("\n✅ All configuration checks passed!")
    return True

def test_connectivity():
    """Test network connectivity."""
    print("\n🌐 Testing network connectivity:")

    import requests
    try:
        response = requests.get('https://api.upstox.com', timeout=10)
        print(f"  ✅ Upstox API reachable (status: {response.status_code})")
    except Exception as e:
        print(f"  ❌ Network error: {e}")
        return False

    return True

def main():
    """Main validation function."""
    print("=" * 50)
    print("  Upstox TOTP Configuration Validator")
    print("=" * 50)

    if not validate_environment():
        print("\n💡 To fix configuration issues:")
        print("  1. Create .env file with required variables")
        print("  2. Run: upstox_cli check-env")
        print("  3. Verify credentials in Upstox app")
        sys.exit(1)

    if not test_connectivity():
        print("\n💡 To fix network issues:")
        print("  1. Check internet connection")
        print("  2. Verify firewall settings")
        print("  3. Check proxy configuration")
        sys.exit(1)

    print("\n🎉 Configuration is valid and ready for use!")

if __name__ == "__main__":
    main()

Save this as validate_config.py and run:

python validate_config.py

Performance Testing

#!/usr/bin/env python3
"""
Performance testing script
"""

import time
import statistics
from upstox_totp import UpstoxTOTP

def benchmark_token_generation(num_runs=5):
    """Benchmark token generation performance."""
    print(f"🚀 Benchmarking token generation ({num_runs} runs)...")

    times = []
    success_count = 0

    for i in range(num_runs):
        start_time = time.time()

        try:
            upx = UpstoxTOTP()
            response = upx.app_token.get_access_token()

            if response.success:
                success_count += 1

        except Exception as e:
            print(f"  Run {i+1} failed: {e}")
            continue

        end_time = time.time()
        duration = end_time - start_time
        times.append(duration)

        print(f"  Run {i+1}: {duration:.2f}s")

    if times:
        print(f"\n📊 Performance Results:")
        print(f"  Success rate: {success_count}/{num_runs} ({success_count/num_runs*100:.1f}%)")
        print(f"  Average time: {statistics.mean(times):.2f}s")
        print(f"  Min time: {min(times):.2f}s")
        print(f"  Max time: {max(times):.2f}s")
        if len(times) > 1:
            print(f"  Std deviation: {statistics.stdev(times):.2f}s")

if __name__ == "__main__":
    benchmark_token_generation()

Getting Help

Self-Help Resources

Check this troubleshooting guide thoroughly
Run the environment validator script
Enable debug mode for detailed error messages
Search existing GitHub issues

Community Support

GitHub Issues: https://github.com/batpool/upstox-totp/issues
Discussions: https://github.com/batpool/upstox-totp/discussions
Reddit: https://www.reddit.com/user/iamdeadloop/

When Reporting Issues

Please include:

Environment information:

python --version
pip show upstox-totp
uname -a  # or systeminfo on Windows

Configuration (without sensitive data):
```
upstox_cli check-env
```
Error messages and stack traces
Steps to reproduce the issue
Expected vs actual behavior

Template for issue reports:

## Environment
- OS: [e.g., Ubuntu 20.04, Windows 10, macOS 12]
- Python version: [e.g., 3.12.0]
- upstox-totp version: [e.g., 1.0.3]

## Problem Description
[Describe what you were trying to do and what went wrong]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [etc.]

## Expected Behavior
[What you expected to happen]

## Actual Behavior
[What actually happened]

## Error Messages
```
[Paste any error messages here]
```

## Configuration Check
```
[Output of: upstox_cli check-env]
```

## Additional Context
[Any other relevant information]

Emergency Contacts

For critical security issues:

Security vulnerabilities: Use GitHub Security tab
Upstox API issues: Contact Upstox support directly
Trading platform issues: Contact your broker

Recovery Procedures

Complete Reset

If all else fails, try a complete reset:

# 1. Backup current configuration
cp .env .env.backup

# 2. Remove all upstox-totp related files
rm -f .env upstox_token.* *.log

# 3. Uninstall and reinstall package
pip uninstall upstox-totp
pip install upstox-totp

# 4. Recreate configuration from scratch
upstox_cli check-env  # This will show what's missing

# 5. Test with minimal configuration
cat > .env << EOF
UPSTOX_USERNAME=your-username
UPSTOX_PASSWORD=your-password
UPSTOX_PIN_CODE=your-pin
UPSTOX_TOTP_SECRET=your-secret
UPSTOX_CLIENT_ID=your-client-id
UPSTOX_CLIENT_SECRET=your-secret
UPSTOX_REDIRECT_URI=your-uri
EOF

# 6. Test step by step
upstox_cli check-env
upstox_cli generate-token

Credential Reset

If you suspect credential issues:

Reset Upstox password via web platform
Regenerate TOTP secret in Upstox app
Create new Developer App if needed
Update all environment variables
Test with new credentials

Troubleshooting Guide

Quick Diagnosis

Environment Check

Debug Mode

Common Issues

Configuration Errors

Authentication Errors

OAuth Errors

Network Errors

Installation Issues

Token Issues

Platform-Specific Issues

Windows Issues

macOS Issues

Linux Issues

Docker Issues

Advanced Debugging

Enable All Logging

Network Traffic Analysis

Memory and Performance Issues

Testing Configuration

Configuration Validation Script

Performance Testing

Getting Help

Self-Help Resources

Community Support

When Reporting Issues

Emergency Contacts

Recovery Procedures

Complete Reset

Credential Reset

See Also