Troubleshooting

Troubleshooting

Common issues and solutions for SIGNula.

---

Installation Issues

Database Connection Failed

Symptom: "Could not connect to database" error

Solutions:

1. Verify credentials in web/_config/config.php
2. Ensure MySQL is running: systemctl status mysql
3. Check the user has permissions: GRANT ALL ON signula_db.* TO 'signula_user'@'localhost';
4. Verify the database exists: SHOW DATABASES LIKE 'signula_db';
5. If using a socket: check DB_HOST is set to localhost (not 127.0.0.1)

Migration Errors

Symptom: SQL errors when running migration files

Solutions:

1. Check which migrations have been applied: SELECT * FROM tblMigrations ORDER BY appliedAt;
2. Run migrations in order (001, 002, ... 013)
3. If ENUM modification fails, the value may already exist - this is safe to skip
4. Check MySQL version compatibility (8.0+ required)

White/Blank Page

Symptom: Empty page with no content

Solutions:

1. Enable debug mode: add ?debug=true to the URL
2. Check PHP error log: tail -f /var/log/php_errors.log
3. Verify PHP extensions are loaded: php -m | grep -i mysqli
4. Check file permissions on web/private_html/
5. Ensure SIGNULA_INIT constant is being defined by the entry point

---

Authentication Issues

Login Not Working

Symptom: Correct credentials but login fails

Solutions:

1. Check tblActivityLog for the login attempt: SELECT * FROM tblActivityLog WHERE eventType = 'login_failed' ORDER BY createdAt DESC LIMIT 5;
2. Verify the account isn't locked (too many failed attempts)
3. Check session configuration in tblSettings
4. Ensure cookies are being set (check browser dev tools)
5. Verify HTTPS is working (sessions require secure cookies)

MFA Code Not Accepted

Symptom: TOTP codes from authenticator app are rejected

Solutions:

1. Check server time is synchronised (NTP): timedatectl status
2. TOTP is time-sensitive; a 30-second drift will cause failures
3. Try the next code (codes rotate every 30 seconds)
4. Use a backup code if available
5. Admin can disable MFA for the user in Admin > Users

OAuth Login Fails

Symptom: "Error during OAuth authentication" message

Solutions:

1. Verify OAuth credentials in Admin > System > OAuth Providers
2. Check the redirect URI matches exactly what's configured with the provider
3. Ensure the OAuth app is approved/published (not in test mode with user limits)
4. Check tblActivityLog for detailed error messages
5. Verify DNS and SSL are correct for your domain

PassKey Not Working

Symptom: WebAuthn registration or authentication fails

Solutions:

1. Ensure HTTPS is active (WebAuthn requires secure context)
2. Check webauthn.rp_id matches your domain exactly
3. Verify the browser supports WebAuthn (modern Chrome, Firefox, Safari, Edge)
4. Try a different authenticator (platform vs roaming)
5. Clear browser credential cache and re-register

---

Payment Issues

Webhook Not Received

Symptom: Payments aren't being recorded after completion

Solutions:

1. Check webhook URL is accessible from the internet (not behind auth)
2. Verify webhook secret/token is correct in SIGNula settings
3. Check Admin > Payments > Webhooks for logged incoming requests
4. Verify the provider's webhook is enabled and pointing to the correct URL:
   • Stripe: https://signulo.id/webhooks/stripe
   • PayPal: https://signulo.id/webhooks/paypal
   • Coinbase: https://signulo.id/webhooks/coinbase
   • Ko-fi: https://signulo.id/webhooks/kofi
   • Patreon: https://signulo.id/webhooks/patreon
5. Test with the provider's webhook testing tool (Stripe CLI, PayPal sandbox)

Webhook Signature Verification Failed

Symptom: 401 response to webhook, "Invalid signature" in logs

Solutions:

1. Regenerate the webhook secret and update both sides
2. For Stripe: ensure you're using the endpoint-specific signing secret (not the API key)
3. For Ko-fi: the verification token is in the payload body, not a header
4. For Patreon: uses HMAC-MD5 (not SHA256)
5. Ensure no middleware/proxy is modifying the request body

Payment Recorded But User Not Activated

Symptom: Webhook received and logged, but user tier/access not updated

Solutions:

1. Check if the user email in the payment matches a tblUsers email
2. Review the webhook log entry status in tblInboundWebhooks
3. Check tblActivityLog for payment processing errors
4. Verify PaymentManager::completePayment() was called successfully

---

API Issues

401 Unauthorized

Symptom: API returns 401 on authenticated endpoints

Solutions:

1. Check API key format: must start with sk_live_ or sk_test_
2. Verify key hasn't been revoked in Partner Dashboard
3. If using Bearer token, check it hasn't expired
4. Ensure the X-API-Key header (not Authorization) is used for API key auth
5. Check IP whitelist restrictions on the API key

429 Too Many Requests

Symptom: Rate limit exceeded

Solutions:

1. Check X-RateLimit-Remaining header for current quota
2. Wait until X-RateLimit-Reset timestamp
3. Implement exponential backoff in your client
4. Request a rate limit increase via the Partner Dashboard
5. Cache responses where possible to reduce API calls

CORS Errors

Symptom: Browser blocks API requests with CORS error

Solutions:

1. Add your domain to the allowed origins in Admin > System > CORS Settings
2. Ensure preflight OPTIONS requests are handled
3. Check that Access-Control-Allow-Origin header is present in responses
4. For development, temporarily allow localhost origins

---

Email Issues

Emails Not Sending

Symptom: Email queue grows but emails don't deliver

Solutions:

1. Check SMTP credentials in Admin > System > Email Settings
2. Verify SMTP port is correct (587 for TLS, 465 for SSL)
3. Check if the SMTP server requires app-specific passwords (Gmail, Microsoft)
4. Review tblEmailQueue for error messages: SELECT * FROM tblEmailQueue WHERE status = 'failed' ORDER BY createdAt DESC LIMIT 10;
5. Test SMTP connection from server: telnet smtp.server.com 587

Delegate Email Not Working

Symptom: OAuth-connected email account fails to send

Solutions:

1. Check token status in Settings > Email Accounts
2. If token is expired, disconnect and reconnect the account
3. Verify OAuth permissions include Mail.Send (Microsoft) or Gmail send scope
4. Check tblUserOAuthTokens for token expiry dates

---

Performance Issues

Slow Page Loads

Solutions:

1. Enable PHP opcode caching (APCu/OPcache)
2. Add database indexes for frequently queried columns
3. Enable gzip compression in web server config
4. Use a CDN for static assets (Bootstrap, FontAwesome)
5. Check tblActivityLog size - archive old entries periodically

High Database Load

Solutions:

1. Review MySQL slow query log
2. Optimise tables: OPTIMIZE TABLE tblActivityLog;
3. Archive old records from tblActivityLog, tblEmailQueue, tblInboundWebhooks
4. Add missing indexes identified in slow query log
5. Consider read replicas for high-traffic deployments

---

Debug Mode

Enabling Debug Mode

Via URL (temporary):

https://signulo.id/page?debug=true

Via database (persistent):

UPDATE tblSettings SET settingValue = '1' WHERE settingKey = 'app.debug';

What Debug Mode Shows

• Detailed PHP error messages
• SQL query logging
• Request/response headers
• Backtrace information

Warning: Never enable debug mode in production. It exposes sensitive information.

---

Getting Help

• GitHub Issues: Report a bug
• Security Issues: SECURITY.md
• Documentation: Full docs index

---

Copyright 2025-2026 MWBM Partners Ltd (t/a MWservices). All rights reserved.