Troubleshooting

Installation Issues

"cargo: command not found"

Rust is not installed. Install from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

"error: linker `cc` not found" / OpenSSL errors

Missing build tools or OpenSSL development libraries.

macOS:

brew install openssl pkg-config
export OPENSSL_DIR=$(brew --prefix openssl)
cargo install pixcli

Ubuntu/Debian:

sudo apt install build-essential libssl-dev pkg-config
cargo install pixcli

Fedora/RHEL:

sudo dnf install gcc libssl-devel pkg-config
cargo install pixcli

Configuration Issues

"No configuration found"

Error: No configuration found. Run `pixcli config init` first.

Create configuration:

pixcli config init

Or set the config path:

export PIXCLI_CONFIG=/path/to/config.toml
pixcli balance

"Certificate not found"

Error: Certificate file not found: /path/to/cert.p12

Check the certificate path:

ls -la ~/.pixcli/certs/

Ensure the path in config.toml matches exactly:

pixcli config show

If the file exists, check permissions:

chmod 600 ~/.pixcli/certs/sandbox.p12

"Certificate password incorrect"

Error: Failed to load certificate: Invalid password

The certificate password in the config is wrong. The Efí sandbox certificate typically has no password.

Update the config:

pixcli config init
# Leave password blank for sandbox

Or set via environment variable:

export PIXCLI_CERTIFICATE_PASSWORD=""
pixcli balance

Authentication Issues

"401 Unauthorized"

Error: Authentication failed (401 Unauthorized)

The Client ID or Client Secret is wrong.

Verify credentials from the Efí dashboard
Update config:

pixcli config init

Test with verbose logging:

pixcli --verbose balance 2>&1 | grep -i "auth\|token"

"403 Forbidden"

Error: Access Denied (403 Forbidden)

Your PSP account doesn't have permission for this operation. Possible causes:

mTLS certificate not signed by Efí — certificate is invalid
Account not fully activated — KYC verification incomplete
Pix key not registered — add the key to your account

Contact Efí support for verification issues.

Network Issues

"Connection refused"

Error: Connection refused

The PSP server is unreachable. Check:

Internet connection:

ping 8.8.8.8

Firewall rules (if behind a proxy):

curl -v https://pix.api.efipay.com.br/

API endpoint availability — check Efí status page

"Timeout"

Error: Request timeout

The PSP is slow to respond. Try with longer timeout:

PIXCLI_TIMEOUT=30 pixcli balance

Or increase retries in your application code:

for attempt in 0..3 {
    match client.get_balance().await {
        Ok(balance) => return Ok(balance),
        Err(_) if attempt < 2 => {
            tokio::time::sleep(Duration::from_secs(2)).await;
            continue;
        }
        Err(e) => return Err(e),
    }
}

API Issues

"Invalid Pix key"

Error: Invalid pix key format

The Pix key doesn't match any valid format. Valid formats:

CPF: 11 digits (e.g., 12345678901)
CNPJ: 14 digits (e.g., 12345678000190)
Phone: +55 + area code + number (e.g., +5511999999999)
Email: valid email (e.g., user@example.com)
EVP: UUID (e.g., 7d9f8a2e-3b4c-4e5f-9a0b-1c2d3e4f5a6b)

"TxID not found"

Error: Charge not found (404)

The transaction ID doesn't exist or already expired. Check:

Verify the TxID is correct:

pixcli charge list

Check if it's from a different profile:

pixcli --profile production charge get <txid>

"Charge already paid"

Error: Cannot modify charge, status is CONCLUIDA

The charge is already paid and can't be edited. Create a new charge instead.

Webhook Issues

"Webhook not receiving events"

Verify registration:

pixcli webhook get --key "+5511999999999"

Check the URL — Efí appends /pix:

# If you registered: https://example.com/webhook
# Efí sends to: https://example.com/webhook/pix

Ensure your server responds with 200 OK:

pixcli webhook listen --port 8080

Test with webhook.site:

pixcli --sandbox webhook register --key "test@key" --url "https://webhook.site/unique-id"

Simulate a payment in the Efí dashboard

"mTLS certificate error"

Error: TLS handshake failed

In production, Efí requires a valid client certificate. Configure nginx to validate:

ssl_client_certificate /etc/ssl/certs/efi-ca.pem;
ssl_verify_client on;

Download efi-ca.pem from the Efí developer portal.

Debug Mode

Enable verbose logging for detailed information:

pixcli --verbose <command> 2>&1 | head -50

Example output:

[DEBUG] Loading config from: /home/user/.pixcli/config.toml
[DEBUG] Selected profile: sandbox
[DEBUG] Certificate loaded: sandbox.p12
[DEBUG] Requesting OAuth2 token from https://pix-api-sandbox.efipay.com/oauth/token
[DEBUG] Token acquired, expires in 3600 seconds
[DEBUG] GET https://pix-api-sandbox.efipay.com/api/v1/getsaldo
[DEBUG] Response: 200 OK

Getting Help

Check the FAQ
Search closed GitHub issues: pixcli/pixcli/issues
Open a new issue with:
- pixcli version: pixcli --version
- OS: uname -a
- Error message (with --verbose)
- Steps to reproduce
Contact Efí support for API-specific issues

Troubleshooting

On this page