> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asquareportal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot common Portals issues step by step

> Step-by-step fixes for common problems in Portals, covering the Portal Agent, authentication, canvas performance, collaboration, and app updates.

Most issues in Portals fall into a small number of categories. Find your problem below and follow the steps to resolve it. If nothing here solves your issue, use the in-app feedback form to contact the team directly.

<AccordionGroup>
  <Accordion title="AI & Portal Agent">
    **Portal Agent is not responding**

    If the agent stops replying or shows an error after you send a message:

    <Steps>
      <Step title="Check your AI provider configuration">
        Open the AI settings panel and confirm that your selected provider is enabled and that any required API key is entered correctly. Keys for OpenAI, Anthropic, Google, and OpenRouter must be valid and have sufficient quota on the provider's side.
      </Step>

      <Step title="Check provider status">
        Visit the status page for your chosen provider (for example, status.openai.com for OpenAI) to see if there is an active incident or outage.
      </Step>

      <Step title="Switch to Pollinations">
        Pollinations is the built-in provider that requires no API key. Switch to it in the AI settings panel to confirm whether the issue is specific to your configured provider or a broader problem with the agent.
      </Step>
    </Steps>

    ***

    **You have hit the beta AI limit**

    When your beta credits are exhausted, AI generation features will stop working until credits are replenished.

    <Steps>
      <Step title="Request more credits via the feedback form">
        Open the feedback form from the toolbar and describe your use case. The team reviews credit requests manually during the early access period.
      </Step>

      <Step title="Connect your own API key">
        Go to the AI settings panel and configure a provider such as OpenAI, Anthropic, or OpenRouter with your own API key. Requests made with your own key bypass the Portals beta credit system entirely.
      </Step>
    </Steps>

    <Warning>
      Beta AI credits and search credits are tracked separately. Exhausting one does not affect the other.
    </Warning>

    ***

    **API key is entered but the agent still returns an error**

    Verify that the key you entered matches the provider type selected (for example, an Anthropic key will not work in the OpenAI slot). Also confirm that the key has not been revoked or expired in your provider's dashboard. For OpenAI-compatible providers, make sure the base URL is set correctly in addition to the key.
  </Accordion>

  <Accordion title="Authentication">
    **Cannot sign in to Portals**

    <Steps>
      <Step title="Check your email address">
        Make sure you are entering the exact email address you registered with, including correct capitalisation and no extra spaces.
      </Step>

      <Step title="Sign out and sign back in">
        If you are already partially signed in or see a stale session, sign out fully from the account menu and then sign in again. This clears any cached session state.
      </Step>

      <Step title="Check for service disruptions">
        If sign-in is failing for everyone, there may be a temporary service disruption. Try again in a few minutes, or report the issue via the in-app feedback form.
      </Step>
    </Steps>

    ***

    **Sign-in link or magic link is not arriving**

    Check your spam or junk folder first. If the email does not arrive after a few minutes, try requesting a new link. Check that your email provider is not filtering messages from Portals' sending domain.

    ***

    **Session keeps expiring unexpectedly**

    Portals keeps your session active automatically. If you are being signed out frequently, check whether any browser extensions or privacy tools are wiping site data between sessions, which would clear your saved login.
  </Accordion>

  <Accordion title="Performance">
    **The canvas feels slow or laggy with many cards**

    Large boards with many cards, images, or applets can tax rendering performance, particularly on older hardware.

    <Steps>
      <Step title="Reduce the number of visible cards">
        Zoom out to reduce the number of fully rendered elements in the viewport, or archive cards you are not actively using.
      </Step>

      <Step title="Close other applications">
        Portals runs as a native desktop app and competes for system memory with other processes. Closing memory-intensive applications frees resources for the canvas renderer.
      </Step>

      <Step title="Check your zoom level">
        Very high zoom levels force the renderer to draw elements at full resolution. Zoom to a level appropriate to the work you are doing.
      </Step>
    </Steps>

    ***

    **App is slow to launch**

    On first launch after an update, Portals may take longer than usual while it initialises updated assets. If startup slowness persists beyond the first run, try quitting the app fully (not just closing the window on Mac) and relaunching.

    ***

    **Gestures or trackpad scrolling feel inconsistent**

    Portals uses custom gesture handling for touch, trackpad, and mouse input with momentum effects. If scrolling or zooming feels off, check that no other app or system setting is intercepting trackpad gestures (for example, some Mac accessibility tools or BetterTouchTool profiles can interfere).
  </Accordion>

  <Accordion title="Collaboration">
    **A teammate's cursor is not visible**

    Real-time cursor presence requires a stable internet connection on both sides.

    <Steps>
      <Step title="Check both users' internet connections">
        Ask your teammate to verify their connection. Even a briefly dropped connection can cause presence to stop syncing.
      </Step>

      <Step title="Rejoin the workspace">
        Both users should leave the workspace and rejoin. This re-establishes the real-time channel and typically restores cursor visibility.
      </Step>
    </Steps>

    ***

    **Changes are not syncing between collaborators**

    <Steps>
      <Step title="Verify both users are in the same workspace">
        Confirm that both users have opened the same workspace URL and are signed into their respective accounts.
      </Step>

      <Step title="Refresh the workspace">
        Close and reopen the workspace on the affected device. This forces a full state sync from the server.
      </Step>
    </Steps>

    <Info>
      Collaboration is in active development during the 0.8.0-alpha period. Brief sync delays are expected and being addressed in upcoming releases.
    </Info>
  </Accordion>

  <Accordion title="Updates">
    **The app shows an update notification**

    When a new version of Portals is available, an "Update Available" banner appears inside the app showing the new version number.

    <Steps>
      <Step title="Click Download in the notification">
        Select the **Download** button in the update banner. The new version will begin downloading.
      </Step>

      <Step title="Relaunch the app">
        Once the download completes, relaunch Portals to apply the update. You can choose **Later** in the notification to postpone until the next launch.
      </Step>
    </Steps>

    ***

    **The update notification appeared but then disappeared**

    If you dismissed the notification, it will reappear the next time you launch the app. You can also dismiss it and manually download the latest version from the Portals website if needed.

    ***

    **The app does not seem to be on the latest version after updating**

    Fully quit the app — on Mac, use **Cmd + Q** or right-click the Dock icon and choose Quit rather than just closing the window — then relaunch. This ensures the updated binary is loaded rather than the previously running instance.
  </Accordion>
</AccordionGroup>

<Tip>
  If none of the steps above resolve your issue, use the in-app feedback form — accessible from the toolbar — to describe what you are experiencing. Include the steps you already tried so the team can investigate efficiently.
</Tip>