Troubleshooting

This guide helps diagnose and resolve common issues with CloudRepo.

Quick Diagnostics

Before diving into specific issues, run these quick checks:

Connection Test

# Test basic connectivity
curl -I https://[org-id].cloudrepo.io

# Test authentication
curl -u username:password https://[org-id].cloudrepo.io/api/user

# Test repository access
curl -u username:password https://[org-id].cloudrepo.io/repository/[repo-name]/

Network Diagnostics

# DNS resolution
nslookup [org-id].cloudrepo.io

# Trace network path
traceroute [org-id].cloudrepo.io

# Check SSL certificate
openssl s_client -connect [org-id].cloudrepo.io:443

Authentication Issues

401 Unauthorized

Symptoms: * “401 Unauthorized” errors * “Authentication failed” messages

Common Causes & Solutions:

Incorrect credentials:

# Test credentials directly
curl -u username:password https://[org-id].cloudrepo.io/api/user

Special characters in password:
- URL-encode special characters
- Use %40 for @, %23 for #, etc.
API key issues:
- Verify API key hasn’t expired
- Check key has correct permissions
- Use “api-key” as username

403 Forbidden

Symptoms: * “403 Forbidden” errors * “Access denied” messages

Solutions:

Check repository permissions: * Verify user has access to repository * Confirm read/write permissions
IP restrictions: * Check if IP allowlisting is enabled * Verify your IP is allowed

Repository Access Problems

404 Not Found

Common Causes:

Incorrect repository URL:

❌ Wrong: https://[org-id].cloudrepo.io/maven-releases
✅ Right: https://[org-id].cloudrepo.io/repository/maven-releases

Repository doesn’t exist: * Verify repository name * Check repository was created

Python simple index:

❌ Wrong: https://[org-id].cloudrepo.io/repository/pypi
✅ Right: https://[org-id].cloudrepo.io/repository/pypi/simple

Artifact Not Found

Debugging Steps:

Verify artifact was uploaded:

curl -u username:password \
  https://[org-id].cloudrepo.io/repository/[repo-name]/[path]

Check artifact path: * Maven: com/example/artifact/1.0/artifact-1.0.jar * Python: Check package name matches
Repository type mismatch: * Ensure uploading to correct repository type * Releases vs. snapshots for Maven

Upload/Download Issues

Slow Performance

Diagnosis:

# Test download speed
time curl -o /dev/null \
  https://[org-id].cloudrepo.io/repository/[repo]/test-file

Solutions:

Network optimization: * Check internet bandwidth * Use CloudRepo CDN endpoints * Configure connection pooling

Client configuration:

Maven - Increase threads

<configuration>
  <maxThreads>10</maxThreads>
</configuration>

Use proxy repositories: * Cache external dependencies * Reduce external downloads

Upload Failures

Large File Uploads:

# Use chunked transfer for large files
curl -u username:password \
  --upload-file large-file.zip \
  --header "Transfer-Encoding: chunked" \
  https://[org-id].cloudrepo.io/repository/raw/large-file.zip

Timeout Issues:

Increase client timeout settings
Use resumable uploads for very large files
Consider splitting into smaller artifacts

SSL/TLS Problems

Certificate Errors

Symptoms: * “SSL certificate problem” * “unable to verify the first certificate”

Solutions:

Update CA certificates:

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

# CentOS/RHEL
sudo yum install ca-certificates

# macOS
brew install ca-certificates

Java applications:

# Import certificate to Java keystore
keytool -import -trustcacerts \
  -keystore $JAVA_HOME/jre/lib/security/cacerts \
  -alias cloudrepo \
  -file cloudrepo.crt

Python applications:

# Update certifi
pip install --upgrade certifi

# Or disable verification (not recommended)
export PYTHONHTTPSVERIFY=0

Build Tool Specific Issues

Maven

Metadata Issues:

# Force metadata update
mvn -U clean install

# Clear local repository cache
rm -rf ~/.m2/repository/com/example/your-artifact

Settings.xml Problems:

# Validate settings.xml
mvn help:effective-settings

# Use specific settings file
mvn -s /path/to/settings.xml deploy

Gradle

Cache Issues:

# Clear Gradle cache
gradle clean build --refresh-dependencies

# Remove specific cached artifact
rm -rf ~/.gradle/caches/modules-2/files-2.1/com.example

Configuration Problems:

// Enable debug logging
gradle.startParameter.showStacktrace = ShowStacktrace.ALWAYS
gradle.startParameter.logLevel = LogLevel.DEBUG

Python/pip

Index Issues:

# Clear pip cache
pip cache purge

# Force reinstall
pip install --force-reinstall --no-cache-dir package-name

Configuration Problems:

# Check current configuration
pip config list

# Set repository URL
pip config set global.index-url https://[org-id].cloudrepo.io/repository/pypi/simple

CI/CD Integration Issues

Environment Variables

Debugging:

# Print environment (mask passwords!)
env | grep CLOUDREPO | sed 's/PASSWORD=.*/PASSWORD=***/'

Common Issues:

Variables not exported
Incorrect variable names
Special characters not escaped

Secret Management

GitHub Actions:

# Debug secrets (safely)
- name: Check secrets
  run: |
    if [ -z "${{ secrets.CLOUDREPO_USERNAME }}" ]; then
      echo "Username secret not set"
    else
      echo "Username secret is configured"
    fi

Jenkins:

// Verify credentials exist
withCredentials([usernamePassword(
  credentialsId: 'cloudrepo-creds',
  usernameVariable: 'USER',
  passwordVariable: 'PASS'
)]) {
  sh 'echo "Credentials loaded successfully"'
}

Common Error Messages

“Connection refused”

Causes: * Firewall blocking connection * Proxy configuration needed * CloudRepo service issue (check status.cloudrepo.io)

“Checksum validation failed”

Solutions: * Re-upload artifact * Clear local cache * Verify network stability

“Repository is read-only”

Causes: * User lacks write permission * Repository configured as read-only * Quota exceeded

Performance Diagnostics

Measuring Performance

Performance test script

import time
import requests

def test_performance(url, auth):
    times = []
    for i in range(10):
        start = time.time()
        response = requests.get(url, auth=auth)
        elapsed = time.time() - start
        times.append(elapsed)
        print(f"Request {i+1}: {elapsed:.2f}s")

    avg = sum(times) / len(times)
    print(f"Average: {avg:.2f}s")

# Run test
test_performance(
    "https://[org-id].cloudrepo.io/repository/maven-releases/test.jar",
    ("username", "password")
)

Debug Logging

Enable Verbose Logging

Maven:

mvn -X deploy

Gradle:

gradle --debug publish

pip:

pip install -v package-name

curl:

curl -v -u username:password https://[org-id].cloudrepo.io/api/user

Analyzing Logs

Look for: * HTTP status codes * Response headers * Error messages * Timing information

Getting Help

Self-Service Resources

Check CloudRepo status: https://status.cloudrepo.io
Review documentation: This guide
Search knowledge base: Knowledge Base

Contacting Support

When contacting support, provide:

Organization ID
Repository name
Error messages (full text)
Steps to reproduce
Debug logs (if available)
Time of occurrence

Email: support@cloudrepo.io Response time: Usually within 2 business hours

Emergency Issues

For critical production issues: * Mark email as “URGENT” * Include business impact * Provide contact phone number

Next Steps

Still Need Help? - FAQs and common issues
Repository Management - Repository configuration
Continuous Integration and Deployment - CI/CD setup
Contact support@cloudrepo.io for unresolved issues