Skip to main content

Troubleshooting

Overview​

This guide provides solutions to common issues encountered during SAMO platform installation and deployment.

Common Issues​

Database Connection Issues​

Problem: Application fails to connect to the database.

Solutions:

  1. Verify database credentials in configuration files
  2. Check database server is running and accessible
  3. Verify network connectivity and firewall rules
  4. Ensure database driver is properly installed
# Test database connectivity
telnet <db-host> <db-port>

Docker Container Issues​

Problem: Docker containers fail to start or stop unexpectedly.

Solutions:

  1. Check Docker logs for error messages:

    docker compose logs -f

  2. Verify Docker resources (memory, CPU):

    docker stats

  3. Ensure all required images are pulled:

    docker compose pull

  4. Check port conflicts:

    netstat -tuln | grep <port>

Service Startup Issues​

Problem: SAMO service fails to start.

Solutions:

  1. Check service logs:

    sudo journalctl -u samo-10 -f

  2. Verify Java version:

    java -version

  3. Check file permissions:

    ls -la /opt/samo-10

  4. Verify environment variables are set correctly

Memory Issues​

Problem: Application runs out of memory (OutOfMemoryError).

Solutions:

  1. Increase JVM heap size in configuration:

    -Xmx4g -Xms2g

  2. Monitor memory usage:

    jstat -gc <pid> 1000

  3. Analyze heap dump for memory leaks

Performance Issues​

Problem: Application responds slowly or times out.

Solutions:

  1. Check database query performance
  2. Verify Elasticsearch and Redis are running properly
  3. Review application logs for bottlenecks
  4. Monitor system resources (CPU, memory, disk I/O)
  5. Check network latency between services

Authentication Issues​

Problem: Users cannot log in or authentication fails.

Solutions:

  1. Verify user credentials in Security Manager
  2. Check LDAP/AD synchronization if configured
  3. Review authentication logs
  4. Verify OAuth2/OIDC configuration if using SSO

SSL/TLS Certificate Issues​

Problem: Certificate errors or HTTPS connection failures.

Solutions:

  1. Verify certificate validity:

    openssl x509 -in certificate.crt -text -noout

  2. Check certificate chain is complete

  3. Ensure certificate matches the domain name

  4. Verify certificate is trusted by the client

Logging and Diagnostics​

Enable Debug Logging​

Edit the logging configuration to enable debug level:

logging.level.com.samo=DEBUG
tip

Enable debug logging only temporarily for troubleshooting, as it generates a large volume of log data and may impact performance.

Collect Diagnostic Information​

When reporting issues, include:

  1. Application version and build number
  2. Complete error messages and stack traces
  3. Relevant log excerpts
  4. System information (OS, Java version, etc.)
  5. Configuration files (sanitized)

Log Locations​

  • Tomcat logs: $TOMCAT_HOME/logs/
  • Service logs: sudo journalctl -u samo-10
  • Docker logs: docker compose logs
  • Application logs: /var/log/samo/ or configured location

Getting Help​

If you cannot resolve the issue:

  1. Check the official SAMO documentation
  2. Review release notes for known issues
  3. Contact SAMO support with diagnostic information
  4. Check community forums for similar issues
info

When contacting support, always include the application version, complete error messages, relevant log excerpts, and system information to expedite the resolution process.

Performance Tuning​

Database Optimization​

  • Create appropriate indexes
  • Update database statistics
  • Configure connection pooling
  • Tune database parameters

Application Optimization​

  • Adjust thread pool sizes
  • Configure caching strategies
  • Optimize query performance
  • Review and adjust timeout values

Infrastructure Optimization​

  • Allocate sufficient resources (CPU, memory)
  • Use SSD storage for better I/O performance
  • Configure proper network bandwidth
  • Implement load balancing for high availability