Skip to main content

​
Overview

This guide helps you diagnose and resolve common issues with LibreDTE Core.

​
Certificate Issues

​
Certificate Loading Fails

Problem: The certificate file cannot be loaded or the password is incorrect.Solution:
  1. Verify the certificate file exists: 
    ls -la /path/to/certificate.pfx
  2. Check file permissions: 
    chmod 600 /path/to/certificate.pfx
  3. Verify the password is correct: 
    use Derafu\Certificate\Service\CertificateLoader;
use Derafu\Certificate\Exception\CertificateException;

try {
    $certificateLoader = new CertificateLoader();
    $certificate = $certificateLoader->loadFromFile(
        '/path/to/certificate.pfx',
        'your-password'
    );
} catch (CertificateException $e) {
    echo "Error: " . $e->getMessage();
}
  4. Ensure OpenSSL extension is installed: 
    php -m | grep openssl
Problem: The digital certificate has expired.Solution:
  1. Check certificate expiration date: 
    $expirationDate = $certificate->getExpirationDate();
echo "Certificate expires on: " . $expirationDate->format('Y-m-d');
  2. Obtain a new certificate from your certification authority
  3. Update your certificate file path in your configuration
Problem: The certificate RUT doesn’t match the emisor RUT.Solution:Ensure the certificate belongs to the correct taxpayer:
$certificateRut = $certificate->getId();
$emisorRut = $emisor->getRUT();

if ($certificateRut !== $emisorRut) {
    throw new Exception("Certificate RUT mismatch");
}

​
CAF (Folio) Issues

​
CAF Validation Errors

Problem: CAF signature validation fails.Solution:
  1. Verify the CAF XML file is not corrupted: 
    cat /path/to/caf.xml
  2. Download a fresh CAF from SII
  3. Ensure the CAF matches the document type: 
    $cafTipo = $cafBag->getTipoDocumento()->getCodigo();
$docTipo = $data['Encabezado']['IdDoc']['TipoDTE'];

if ($cafTipo !== $docTipo) {
    throw new Exception("CAF type mismatch");
}
Problem: The requested folio is not within the CAF range.Solution:
  1. Check the CAF range: 
    echo "CAF range: " . $caf->getFolioDesde() . " - " . $caf->getFolioHasta();
  2. Request a new CAF range from SII if folios are exhausted
  3. Use a folio within the valid range: 
    $folio = $caf->getFolioDesde(); // Start from first available
Problem: The CAF was issued for a different taxpayer.Solution:Verify RUT consistency:
$cafRut = $caf->getEmisor()['rut'];
$emisorRut = $emisor->getRUT();

if ($cafRut !== $emisorRut) {
    throw new Exception("CAF does not belong to this emisor");
}

​
SII Integration Issues

​
Authentication Failures

Problem: Connection to SII authentication service times out.Solution:
  1. Check internet connectivity: 
    ping sii.cl
  2. Verify firewall allows HTTPS connections to SII
  3. Check if SII services are operational: SII Status
  4. Increase timeout in your HTTP client configuration
Problem: Authentication token is rejected by SII.Solution:
  1. Request a fresh token: 
    $token = $siiLazyWorker->authenticate(new SiiRequest($certificate));
  2. Ensure your certificate is valid and not expired
  3. Verify you’re using the correct environment (certification vs production)
Problem: SOAP webservice communication fails.Solution:
  1. Verify SOAP extension is installed: 
    php -m | grep soap
  2. Enable SOAP error reporting: 
    ini_set('soap.wsdl_cache_enabled', 0);
ini_set('soap.wsdl_cache_ttl', 0);
  3. Check SII webservice URLs are accessible

​
Document Sending Failures

Problem: SII rejects the submitted document.Solution:
  1. Validate the XML schema before sending: 
    $validator->validateSchema($xml);
  2. Check SII error response for specific rejection reasons
  3. Verify document signature: 
    $validator->validateSignature($xml);
  4. Ensure all required fields are present and valid
Problem: Cannot retrieve document status using track ID.Solution:
  1. Wait a few minutes - SII processing may be delayed
  2. Verify you’re using the correct track ID
  3. Check the correct environment (certification vs production)
  4. Verify the track ID belongs to your RUT

​
PHP Extension Issues

​
Missing Extensions

LibreDTE Core requires specific PHP extensions. Missing extensions will cause runtime errors.
Problem: OpenSSL extension is not installed.Solution:Install the extension based on your OS:Ubuntu/Debian:
sudo apt-get install php8.5-openssl
sudo systemctl restart php8.5-fpm
CentOS/RHEL:
sudo yum install php-openssl
sudo systemctl restart php-fpm
macOS:
brew install [email protected]
Problem: SOAP extension is not installed.Solution:Ubuntu/Debian:
sudo apt-get install php8.5-soap
sudo systemctl restart php8.5-fpm
CentOS/RHEL:
sudo yum install php-soap
sudo systemctl restart php-fpm
Problem: cURL extension is not installed.Solution:Ubuntu/Debian:
sudo apt-get install php8.5-curl
sudo systemctl restart php8.5-fpm
CentOS/RHEL:
sudo yum install php-curl
sudo systemctl restart php-fpm

​
Document Generation Issues

​
XML Validation Errors

Problem: Generated XML doesn’t match SII schema.Solution:
  1. Validate data before building: 
    // Ensure all required fields are present
if (!isset($data['Encabezado']['IdDoc']['TipoDTE'])) {
    throw new Exception("TipoDTE is required");
}
  2. Check for invalid characters in text fields
  3. Verify numeric fields contain valid numbers
  4. Review SII documentation for field requirements
Problem: Cannot render document to PDF.Solution:
  1. Ensure mPDF or TCPDF is installed: 
    composer show mpdf/mpdf
composer show tecnickcom/tcpdf
  2. Check memory limit: 
    ini_set('memory_limit', '256M');
  3. Verify write permissions on temp directory

​
Performance Issues

Problem: Document creation takes too long.Solution:
  1. Enable OPcache: 
    opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
  2. Use caching for repeated operations: 
    use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$cache = new FilesystemAdapter();
  3. Optimize autoloading: 
    composer dump-autoload --optimize

​
Debug Mode

​
Enable Detailed Error Messages

Enable debug mode during development to get detailed error information.
// Enable error reporting
error_reporting(E_ALL);
ini_set('display_errors', 1);

// Enable exception traces
set_exception_handler(function($exception) {
    echo $exception->getMessage() . "\n";
    echo $exception->getTraceAsString();
});

​
Getting Help

If you can’t resolve your issue:
  1. Check the FAQ for common questions
  2. Review the Examples for working code
  3. Search GitHub Issues
  4. Create a new issue with:
    • PHP version (php -v)
    • LibreDTE Core version
    • Complete error message
    • Minimal code to reproduce the issue

Build docs developers (and LLMs) love

Get started for freeTalk to us