Troubleshooting

This guide covers common issues you might encounter while using SAMS and provides step-by-step solutions to resolve them.

Authentication Issues

Cannot Sign In

Symptoms:

• Login page shows error messages
• Account appears to be locked
• Two-factor authentication not working
• Password reset not working

Solutions:

Check Account Status

1. Verify your email address is correct
2. Check if your account needs email verification
3. Ensure your account hasn't been suspended
4. Contact support if account appears locked

Password Issues

1. Use the "Forgot Password" link on login page
2. Check your email (including spam folder) for reset instructions
3. Ensure new password meets security requirements
4. Clear browser cache and try again

Two-Factor Authentication Problems

1. Ensure your device time is synchronized
2. Try using backup codes if available
3. Regenerate 2FA if codes consistently fail
4. Contact support for 2FA reset if needed

Authentication Loops

Symptoms:

• Redirected back to login after successful authentication
• Endless redirect loops
• Session immediately expires

Solutions:

1. Clear browser cookies and cache
2. Disable browser extensions temporarily
3. Try incognito/private browsing mode
4. Check if JavaScript is enabled
5. Try different browser or device

Organization Issues

Cannot Access Organization

Symptoms:

• Organization not visible in switcher
• "Access Denied" when visiting organization URL
• Cannot see organization applications or settings

Solutions:

Check Organization Membership

1. Verify you're a member of the organization
2. Ask organization admin to check your membership status
3. Ensure invitation was accepted if recently invited
4. Check if you're using the correct email address

URL and Slug Issues

1. Verify organization slug is spelled correctly
2. Check if organization has been renamed
3. Try accessing through organization switcher instead of direct URL
4. Contact organization admin if URL has changed

Cannot Create Organization

Symptoms:

• "Create Organization" button not available
• Error when trying to create organization
• Slug validation errors

Solutions:

Permission Issues

1. Check if your account has organization creation permissions
2. Verify account is fully activated and verified
3. Contact support if creation is restricted

Slug Problems

1. Choose a unique organization slug
2. Avoid reserved words (admin, api, settings, etc.)
3. Use only letters, numbers, and hyphens
4. Keep slug length reasonable (3-50 characters)

Application and Subscription Issues

Application Not Accessible

Symptoms:

• Application missing from dashboard
• Cannot access application features
• API calls returning authentication errors

Solutions:

Check Subscription Status

1. Verify organization has active subscription
2. Check if subscription has expired or been cancelled
3. Ensure billing information is current
4. Contact admin if subscription appears active but access denied

Permission Issues

1. Verify you have appropriate organization role
2. Check if application requires specific permissions
3. Ask organization admin to verify your access
4. Ensure you're in the correct organization context

API Token Issues

Symptoms:

• API calls returning 401 Unauthorized
• Token appears invalid or expired
• Cannot generate new tokens

Solutions:

Token Validation

1. Verify token is copied correctly without extra spaces
2. Check token hasn't been revoked or expired
3. Ensure token has appropriate permissions for the operation
4. Verify you're using correct authentication header format

Permission Problems

1. Check if your organization role allows token creation
2. Verify application subscription includes API access
3. Ensure token scope matches required permissions
4. Contact organization admin for access review

Billing and Payment Issues

Payment Failures

Symptoms:

• Subscription cancelled due to payment failure
• Credit card declined
• Cannot update payment method

Solutions:

Card Issues

1. Verify card information is correct
2. Check card expiration date
3. Ensure sufficient funds are available
4. Contact your bank about international/online transaction blocks

Billing Address

1. Verify billing address matches card on file
2. Check ZIP/postal code is correct
3. Ensure country and state information is accurate
4. Update address if you've moved recently

Alternative Payment Methods

1. Try different credit/debit card
2. Use ACH bank transfer if available
3. Contact support for alternative payment options
4. Consider annual billing to reduce payment frequency

Subscription Issues

Symptoms:

• Plan change didn't take effect
• Features missing after upgrade
• Cannot downgrade plan

Solutions:

Plan Changes

1. Check if plan change is scheduled for next billing cycle
2. Verify upgrade took effect and features are available
3. Contact support if downgrade restrictions are unclear
4. Review usage to ensure it fits within new plan limits

Feature Access

1. Log out and log back in to refresh permissions
2. Clear browser cache and cookies
3. Check if feature requires organization admin role
4. Verify subscription includes the specific feature

Performance Issues

Slow Loading

Symptoms:

• Pages take long time to load
• API calls timing out
• Dashboard unresponsive

Solutions:

Browser Optimization

1. Clear browser cache and cookies
2. Disable unnecessary browser extensions
3. Update browser to latest version
4. Try different browser or incognito mode

Network Issues

1. Check internet connection speed
2. Try different network (mobile data, different WiFi)
3. Disable VPN temporarily to test
4. Contact your IT department about firewall restrictions

Performance Troubleshooting

1. Check SAMS status page for known issues
2. Monitor performance during different times of day
3. Report persistent performance issues to support
4. Provide browser console errors when reporting issues

Integration Issues

Symptoms:

• Webhooks not being delivered
• API integrations failing intermittently
• Data sync issues between systems

Solutions:

Webhook Troubleshooting

1. Verify webhook URL is accessible from internet
2. Check webhook endpoint returns proper HTTP status codes
3. Validate webhook signature if using secret verification
4. Monitor webhook delivery logs in SAMS

API Integration Issues

1. Implement proper error handling and retry logic
2. Check API rate limits and implement backoff strategies
3. Monitor API response times and error rates
4. Update API tokens if authentication issues persist

Data and Settings Issues

Missing Data

Symptoms:

• Applications or organizations not showing
• Settings changes not saving
• Data appears to be lost

Solutions:

Organization Context

1. Verify you're in the correct organization
2. Check if data belongs to different organization
3. Switch organizations to locate missing data
4. Contact admin if data access issues persist

Browser Issues

1. Disable browser extensions that might interfere
2. Clear browser cache and local storage
3. Try accessing from different browser or device
4. Check if JavaScript errors are preventing data loading

Settings Not Saving

Symptoms:

• Changes revert after page refresh
• "Save" button appears disabled
• Error messages when trying to save

Solutions:

Form Validation

1. Check for required fields not filled out
2. Verify data format meets requirements (email format, etc.)
3. Look for error messages near form fields
4. Ensure all dropdowns have valid selections

Permission Issues

1. Verify you have permission to modify settings
2. Check if settings require organization admin role
3. Contact admin if permissions appear incorrect
4. Try refreshing page and attempting save again

Mobile and Browser Issues

Mobile Access Problems

Symptoms:

• App not displaying correctly on mobile
• Touch interactions not working
• Features missing on mobile

Solutions:

Mobile Browser Issues

1. Use latest version of mobile browser
2. Try different mobile browser (Chrome, Safari, Firefox)
3. Clear mobile browser cache and data
4. Ensure JavaScript is enabled in mobile browser

Responsive Design Issues

1. Rotate device to landscape mode if needed
2. Zoom out if interface appears too large
3. Use desktop browser for complex administrative tasks
4. Report mobile-specific issues to support

Browser Compatibility

Symptoms:

• Features not working in specific browser
• Layout appears broken
• JavaScript errors in console

Solutions:

Browser Support

1. Use modern browsers (Chrome, Firefox, Safari, Edge)
2. Update browser to latest version
3. Avoid Internet Explorer (no longer supported)
4. Enable JavaScript and cookies

Extension Conflicts

1. Disable browser extensions temporarily
2. Whitelist SAMS domains in ad blockers
3. Disable privacy extensions that might block functionality
4. Try incognito/private mode to test without extensions

Getting Help

Self-Service Resources

Documentation

• Search this documentation for specific topics
• Check getting started guide for basic setup
• Review feature-specific guides for detailed instructions
• Use API documentation for integration help

AI Chatbot

• Access chatbot at /app/chatbot for immediate assistance
• Ask specific questions about features and functionality
• Get help with common troubleshooting steps
• Receive guidance on best practices

Contacting Support

When to Contact Support

• Issues not resolved by troubleshooting steps
• Account access problems requiring admin intervention
• Billing and payment issues
• Security concerns or suspicious activity
• Bug reports and feature requests

Information to Provide

• Detailed description of the issue
• Steps you've already tried
• Browser and operating system information
• Organization name and user email
• Screenshots or error messages if available
• Time when issue occurred

Support Channels

• Email support for non-urgent issues
• Live chat during business hours for immediate help
• Priority support for Team and Business plan customers
• Emergency contact for security incidents

Community Resources

User Forums

• Connect with other SAMS users
• Share best practices and tips
• Get community-driven solutions
• Participate in feature discussions

Knowledge Base

• Comprehensive articles and tutorials
• Video guides and walkthroughs
• Best practice recommendations
• Integration examples and templates

Prevention and Best Practices

Avoiding Common Issues

Regular Maintenance

1. Keep browser updated to latest version
2. Clear cache and cookies periodically
3. Review and rotate API tokens regularly
4. Monitor subscription usage and limits

Security Practices

1. Use strong, unique passwords
2. Enable two-factor authentication
3. Regularly review account activity
4. Keep backup codes in secure location

Data Management

1. Export important data regularly
2. Document integrations and configurations
3. Monitor organization member access
4. Keep contact information current

Monitoring and Alerting

Proactive Monitoring

1. Set up billing alerts for usage limits
2. Monitor API token usage and access
3. Review application performance regularly
4. Track organization activity and growth

Issue Prevention

1. Test integrations in staging environment
2. Implement proper error handling in code
3. Monitor third-party service dependencies
4. Keep documentation and procedures current

By following these troubleshooting steps and best practices, you can resolve most common issues quickly and maintain a smooth SAMS experience. When in doubt, don't hesitate to contact support for assistance.