Promptless · promptless · May 12, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
@@ -0,0 +1,148 @@
+---
+title: Integration Connection Issues
+description: Resolve OAuth failures, permission errors, and app installation problems with Promptless integrations.
+slug: docs/troubleshooting/integration-connection-issues
+sidebar:
+  hidden: false
+  order: 24
+---
+import Accordion from '@components/fern/Accordion.astro';
+
+This page helps you diagnose and fix problems when connecting or maintaining integrations with Promptless.
+
+## GitHub Integration Issues
+
+<Accordion title="GitHub App installation isn't appearing">
+**Symptoms**: You installed the Promptless GitHub App but it doesn't show as connected in the dashboard, or repositories aren't appearing.
+
+**Likely causes**:
+- The app was installed to a different organization than the one you're logged into
+- The app installation was started but not completed
+- Browser caching issues
+
+**Solutions**:
+1. Confirm you're logged into the correct Promptless organization at [app.gopromptless.ai](https://app.gopromptless.ai).
+2. Check GitHub directly: go to your GitHub organization Settings → Integrations → Applications and verify Promptless appears in the list.
+3. If the app appears in GitHub but not Promptless, try disconnecting and reconnecting from the [Integrations page](https://app.gopromptless.ai/integrations).
+4. Clear your browser cache and refresh the page.
+</Accordion>
+
+<Accordion title="Permission errors when Promptless tries to access repositories">
+**Symptoms**: Promptless reports permission errors, can't read repository contents, or can't create pull requests.
+
+**Likely causes**:
+- The GitHub App doesn't have access to the specific repository
+- Repository permissions were restricted during installation
+- The repository is in a different organization
+
+**Solutions**:
+1. In GitHub, go to Settings → Integrations → Applications → Promptless → Configure.
+2. Check whether Promptless has access to "All repositories" or "Only select repositories."
+3. If using selective access, add the missing repository to the list.
+4. For organization-owned repositories, ensure the GitHub App is installed at the organization level, not just your personal account.
+</Accordion>
+
+<Accordion title="Webhook delivery failures">
+**Symptoms**: PRs aren't triggering Promptless, or there's a delay between PR activity and Promptless response.
+
+**Likely causes**:
+- Network issues between GitHub and Promptless
+- Webhook configuration was modified
+- GitHub Enterprise firewall blocking outbound webhooks
+
+**Solutions**:
+1. Check webhook delivery status in GitHub: repository Settings → Webhooks → Recent Deliveries.
+2. Look for failed deliveries (red X icons) and examine the response codes.
+3. For GitHub Enterprise, ensure the Promptless IP addresses are whitelisted. See the [GitHub Enterprise Integration](/docs/integrations/github-enterprise-integration) guide.
+4. If webhooks are failing consistently, contact [help@gopromptless.ai](mailto:help@gopromptless.ai).
+</Accordion>
+
+## Slack Integration Issues
+
+<Accordion title="Slack app not responding to mentions">
+**Symptoms**: You @mention Promptless in Slack but nothing happens—no reaction, no response.
+
+**Likely causes**:
+- The Promptless Slack app isn't installed in your workspace
+- Promptless doesn't have access to the channel
+- The Slack integration was disconnected
+
+**Solutions**:
+1. Check the [Integrations page](https://app.gopromptless.ai/integrations) to confirm Slack shows as connected.
+2. In Slack, try inviting @Promptless to the channel using `/invite @Promptless`.
+3. If Slack was recently reconnected, you may need to re-invite Promptless to private channels.
+4. Try using the Promptless message action (click the three dots on a message → "Update Docs") instead of @mention to verify the integration works.
+</Accordion>
+
+<Accordion title="Missing file attachments in Slack threads">
+**Symptoms**: When Promptless responds in Slack, diff files aren't appearing as attachments.
+
+**Likely causes**:
+- Slack permissions were revoked or changed
+- OAuth scopes need to be re-authorized
+
+**Solutions**:
+1. Go to the [Integrations page](https://app.gopromptless.ai/integrations) and re-authorize the Slack connection.
+2. After re-authorizing, diff files should appear as thread attachments.
+3. If the issue persists, contact [help@gopromptless.ai](mailto:help@gopromptless.ai).
+</Accordion>
+
+## Microsoft Teams Integration Issues
+
+<Accordion title="Teams bot not responding">
+**Symptoms**: Promptless doesn't respond to @mentions or message actions in Teams.
+
+**Likely causes**:
+- The Promptless Teams app needs to be added to the specific team or channel
+- The integration was disconnected
+- Teams admin policies are blocking third-party apps
+
+**Solutions**:
+1. Verify Teams shows as connected on the [Integrations page](https://app.gopromptless.ai/integrations).
+2. Add the Promptless app to your team: in Teams, go to Apps → search "Promptless" → Add to a team.
+3. Check with your Teams administrator if third-party app installations require approval.
+</Accordion>
+
+## OAuth and Authentication Errors
+
+<Accordion title="OAuth callback errors during connection">
+**Symptoms**: When connecting an integration, you see an error after the OAuth authorization screen, or the browser redirects to an error page.
+
+**Likely causes**:
+- Pop-up blockers interfering with the OAuth flow
+- Session timeout during the authorization process
+- Browser extensions blocking redirects
+
+**Solutions**:
+1. Disable pop-up blockers temporarily for app.gopromptless.ai.
+2. Try the connection process in an incognito/private browser window.
+3. Ensure you complete the OAuth flow promptly—sessions can timeout if left idle.
+4. If using a corporate proxy, confirm it allows connections to OAuth providers (github.com, slack.com, etc.).
+</Accordion>
+
+<Accordion title="Integration shows connected but stops working">
+**Symptoms**: An integration that previously worked now fails, even though it still shows as connected.
+
+**Likely causes**:
+- OAuth tokens expired and couldn't be refreshed
+- Permissions were revoked in the third-party service
+- The connected account no longer has access to the resources
+
+**Solutions**:
+1. Disconnect the integration from the [Integrations page](https://app.gopromptless.ai/integrations).
+2. Reconnect using an account that has the necessary permissions.
+3. For GitHub, ensure the user reconnecting has admin access to the repositories Promptless needs.
+4. For Slack, the reconnecting user should be a workspace admin or have permission to install apps.
+</Accordion>
+
+## General Connection Tips
+
+When troubleshooting any integration:
+
+1. **Check the Integrations page first**: [app.gopromptless.ai/integrations](https://app.gopromptless.ai/integrations) shows the connection status for all services.
+
+2. **Review recent events**: The [Triggers page](https://app.gopromptless.ai/triggers) shows processing history and any errors.
+
+3. **Reconnect as a solution**: Many issues resolve by disconnecting and reconnecting the integration. This refreshes OAuth tokens and re-syncs permissions.
+
+4. **Contact support with details**: When reaching out to [help@gopromptless.ai](mailto:help@gopromptless.ai), include which integration is affected, what you expected to happen, and any error messages from the dashboard or third-party service.
@@ -0,0 +1,128 @@
+---
+title: Suggestion Quality Issues
+description: Improve Promptless suggestions that miss context, don't match your style, or target the wrong files.
+slug: docs/troubleshooting/suggestion-quality-issues
+sidebar:
+  hidden: false
+  order: 25
+---
+import Accordion from '@components/fern/Accordion.astro';
+
+This page covers issues where Promptless suggestions miss context, don't match your style, or target the wrong files.
+
+## Suggestions Miss Important Context
+
+<Accordion title="Suggestion doesn't include relevant information from the PR or conversation">
+**Symptoms**: The suggestion omits key details that were clearly stated in the PR description, code comments, or Slack thread.
+
+**Likely causes**:
+- The trigger didn't include enough context for Promptless to understand the full scope
+- Related tickets or issues weren't linked
+- Context sources aren't configured
+
+**Solutions**:
+1. **Add more context to triggers**: Include detailed PR descriptions, link to relevant tickets, and reference related conversations.
+2. **Connect context sources**: Configure [Linear](/docs/configuring-promptless/context-sources/linear), [Jira](/docs/configuring-promptless/context-sources/jira), or [Confluence](/docs/configuring-promptless/context-sources/confluence) so Promptless can pull additional information.
+3. **Use follow-up messages**: After receiving a suggestion, reply in Slack or comment on the PR with the missing context. Promptless will incorporate it into an updated suggestion.
+</Accordion>
+
+<Accordion title="Suggestion doesn't reflect related features or existing documentation">
+**Symptoms**: Promptless creates content that contradicts existing docs or doesn't account for related features already documented.
+
+**Likely causes**:
+- The doc collection's index may be outdated
+- The relevant existing pages weren't identified during analysis
+
+**Solutions**:
+1. **Provide explicit references**: In your trigger message, mention specific existing pages that relate to the update.
+2. **Use feedback**: After receiving the suggestion, provide feedback explaining the relationship to existing content. Promptless learns from this for future suggestions.
+3. **Check doc collection sync**: Verify your doc collection is properly synced on the [Settings page](https://app.gopromptless.ai/settings).
+</Accordion>
+
+## Suggestions Don't Match Your Style
+
+<Accordion title="Tone or voice doesn't match existing documentation">
+**Symptoms**: Suggestions use different phrasing, formality level, or terminology than your established docs.
+
+**Likely causes**:
+- Promptless hasn't fully learned your documentation style yet
+- Your docs have inconsistent voice across pages
+- Voice Match isn't enabled
+
+**Solutions**:
+1. **Enable Voice Match**: Contact our team to enable Voice Match for your organization. This feature analyzes your existing docs and fine-tunes suggestions to match.
+2. **Provide style feedback**: When rejecting or editing suggestions, explain what didn't match your style. For example: "We use 'select' instead of 'click' and avoid second person."
+3. **Update your style guide**: Add your preferences to the Agent Knowledge Base. See [How Promptless Learns Your Docs](/docs/configuring-promptless/doc-collections/how-promptless-learns-your-docs).
+</Accordion>
+
+<Accordion title="Formatting doesn't match your conventions">
+**Symptoms**: Suggestions use different heading styles, list formats, callout types, or code block conventions than your docs.
+
+**Likely causes**:
+- Promptless hasn't seen enough examples of your formatting patterns
+- Your docs use custom components that Promptless isn't recognizing
+
+**Solutions**:
+1. **Provide formatting feedback**: When editing suggestions, note the formatting changes you made. Promptless learns from these edits.
+2. **Document your conventions**: Add formatting guidelines to your AGENTS.md file or the Agent Knowledge Base.
+3. **Edit and approve**: Even if you need to adjust formatting, approving edited suggestions teaches Promptless your preferences over time.
+</Accordion>
+
+## Suggestions Target Wrong Files or Locations
+
+<Accordion title="Updates go to the wrong page">
+**Symptoms**: Promptless suggests changes to a page that isn't the right location for the content.
+
+**Likely causes**:
+- Multiple pages cover similar topics
+- The PR or trigger didn't specify where updates should go
+- The relevant page has an unclear title or description
+
+**Solutions**:
+1. **Be explicit about location**: In your trigger (PR description, Slack message, etc.), specify which page should be updated.
+2. **Provide feedback**: Reject the suggestion with an explanation like "This should go in the API Reference section, not the Getting Started guide."
+3. **Review page metadata**: Ensure your docs pages have clear, descriptive titles and frontmatter descriptions that help Promptless identify appropriate locations.
+</Accordion>
+
+<Accordion title="Suggestion creates a new page when it should update existing content">
+**Symptoms**: Promptless proposes a new documentation page for content that should be added to an existing page.
+
+**Likely causes**:
+- The existing page wasn't identified as relevant
+- The trigger described the content as a new topic
+
+**Solutions**:
+1. **Reference existing pages**: In your trigger, mention "Update the existing [Page Name] page" to guide Promptless.
+2. **Provide feedback**: If Promptless creates a new page inappropriately, reject with feedback explaining where the content belongs.
+3. **Check for duplicate content**: Review your docs for overlapping topics that might confuse page selection.
+</Accordion>
+
+## Improving Suggestion Quality Over Time
+
+Promptless learns from your feedback. Here's how to make feedback most effective:
+
+### In Slack
+Reply to suggestions with specific guidance:
+- "Add the error codes we discussed earlier in the thread"
+- "Use the same structure as the existing API endpoint documentation"
+- "This should be more concise—one paragraph instead of three"
+
+### In GitHub
+Comment on Promptless PRs with detailed requests:
+- "Please use our standard callout format for the warning"
+- "The code example should show Python, not JavaScript"
+- "Include a link to the related configuration page"
+
+### In the Dashboard
+Use the feedback features to:
+- Highlight text and explain why it's wrong
+- Approve with edits to show preferred phrasing
+- Reject with explanation when the approach is wrong
+
+### Update the Agent Knowledge Base
+For persistent preferences, add guidance to your [Agent Knowledge Base](/docs/how-to-use-promptless/agent-knowledge-base):
+- Style conventions and terminology
+- Page structure templates
+- Content guidelines for different doc types
+
+The more specific your feedback, the faster Promptless adapts to your preferences.