When you’re stuck troubleshooting a Mattermost deployment issue, sometimes all you need is a little push in the right direction, and that’s where Mattermost Copilot can shine.
But here’s the trick: the quality of your answer depends on the quality of your prompt.
In this post, you’ll learn how to:
- Write a clear, structured troubleshooting prompt for Mattermost Copilot.
- Include the right context to get specific, useful advice.
- Use examples and reproducible steps to help you get unstuck faster.
Why Prompting Matters
AI tools are great at pattern recognition and generating helpful steps, but they need specific, complete input to give their best answers. When you provide detailed context (such as logs, environment details, and what you’ve tried), you’ll get better, more actionable responses.
The Prompt Recipe (Copy & Paste Friendly)
Here’s the ultimate prompt template to use with Mattermost Co-pilot:
Act as the world’s top Mattermost deployment and troubleshooting expert.
I’m experiencing a technical issue and need detailed, step-by-step troubleshooting advice.
Please consider all possible causes, including edge cases, and help me debug efficiently.
Issue Summary: [Brief description of the problem]
Deployment Type: [Cloud / Self-hosted]
Mattermost Version: [e.g., v9.3.0]
Environment: [e.g., Docker, Kubernetes, OS, DB type/version]
Error Messages: [Paste logs or errors]
Steps to Reproduce:
1. [Step 1]
2. [Step 2]
3. [Expected vs. actual result]
What I’ve Tried So Far: [Any configs checked, logs reviewed, etc.]
Please walk me through potential root causes, how to validate them, and what next steps to take.
Example 1: SAML SSO Login Failing
Act as the world’s top Mattermost deployment and troubleshooting expert.
I’m experiencing a technical issue and need detailed, step-by-step troubleshooting advice. Please consider all possible causes, including edge cases, and help me debug efficiently.
Issue Summary: Users are unable to log in via SAML SSO. The login screen refreshes, but no redirect happens.
Deployment Type: Self-hosted
Mattermost Version: v9.3.0
Environment: Docker on Ubuntu 22.04, PostgreSQL 15, NGINX reverse proxy
Error Messages: Server logs show:
{"level":"error","ts":...,"caller":"saml/saml.go:123","msg":"SAML login failed: Invalid response received"}
Steps to Reproduce:
1. Navigate to login page
2. Click “Login with SAML”
3. Page refreshes with no redirect to IdP
What I’ve Tried So Far:
- Verified SAML configuration and IdP metadata
- Checked NGINX config for redirect issues
- Reviewed logs for more detailed errors
- Cleared browser cache and cookies
This prompt will return a step-by-step analysis, including where to look in your SAML config, what logs to trace, and how to validate your IdP connection.
Example 2: Plugins Not Showing in System Console
Act as the world’s top Mattermost deployment and troubleshooting expert.
I’m experiencing a technical issue and need detailed, step-by-step troubleshooting advice. Please consider all possible causes, including edge cases, and help me debug efficiently.
Issue Summary: Plugins are not loading in the System Console even though they’re in the plugin directory.
Deployment Type: Self-hosted
Mattermost Version: v9.2.1
Environment: Bare metal Ubuntu server, PostgreSQL 14, no Docker
Error Messages: No errors in UI. Server log includes:
"Plugin manifest not found for plugin: my-custom-plugin"
Steps to Reproduce:
1. Move plugin `.tar.gz` file to `/opt/mattermost/plugins/`
2. Restart Mattermost
3. Navigate to System Console → Plugins → Nothing listed
What I’ve Tried So Far:
- Double-checked plugin format and directory
- Gave full read/write permissions to plugin folder
- Restarted Mattermost and checked logs
- Confirmed `Enable Plugins` is set to `true` in config.json
This will likely return steps to confirm your plugin file structure, validate permissions, and confirm how Mattermost parses plugin manifests.
Bonus Tip: Link to Docs + GitHub Issues
Copilot loves context! If you reference relevant Mattermost Docs or GitHub Issues, it can ground the response and give you even better results.
Wrap-Up
When you’re troubleshooting Mattermost, Co-pilot is like a sidekick that loves details. Use this prompt recipe any time you hit a snag, and you’ll dramatically improve the speed and quality of your debugging process.
Let us know if you’ve found success with this format, or drop your own prompt examples below!