R
Rideful Slides

Common Error Troubleshooting

Quick fixes for the most common errors you'll encounter when using Rideful's MCP tools — from authentication issues to validation failures.

This page covers errors returned by Rideful's MCP tools, organized by category. Each entry shows the error message, what causes it, and how to fix it.

Authentication Errors

These errors occur when the MCP connection isn't authenticated or the session has expired.

User authentication required

  • Cause: Missing or invalid OAuth token. The MCP client hasn't completed the authorization flow, or the token has expired.
  • Fix: Disconnect and reconnect the MCP server in your client settings. This triggers a fresh OAuth flow. See Connect via MCP for platform-specific instructions.

Authentication failed

  • Cause: The OAuth callback didn't complete successfully — often caused by browser pop-up blockers or navigating away during the flow.
  • Fix: Remove the MCP server from your client, re-add it, and complete the sign-in flow without interruption.

Not Found Errors

These errors occur when referencing a deck, slide, element, or template that doesn't exist or belongs to another user.

Deck not found

  • Cause: The deck ID doesn't exist, is malformed, or belongs to another user.
  • Fix: Call slides_list_decks to see your available decks and verify the ID.

Slide not found / Slide does not belong to this deck

  • Cause: Invalid slide ID, or the slide belongs to a different deck than the one specified.
  • Fix: Call slides_get_deck to see all slide IDs for a specific deck.

Element not found / Element does not belong to this deck

  • Cause: Invalid element ID, or the element belongs to a different deck.
  • Fix: Call slides_get_slides to retrieve all element IDs on a slide before modifying them.

Template not found / Layout not found

  • Cause: Invalid template or layout ID, or the layout doesn't belong to the specified template.
  • Fix: Call slides_list_templates to get template IDs, then slides_list_template_layouts to get layout IDs for a specific template.

Validation Errors

These errors occur when tool parameters are missing, invalid, or conflict with each other.

Missing required fields

Messages like Deck ID is required, x and y position are required, or width and height are required.

  • Fix: Provide all required parameters. Shape and text elements always need x, y, width, and height. Line elements need start/end coordinates or anchors.

Invalid element or shape type

Messages like elementType must be 'shape', 'text', or 'line' or shapeType must be 'rectangle', 'circle', or 'diamond'.

  • Valid element types: shape, text, line
  • Valid shape types: rectangle, circle, diamond
  • Shape elements always require shapeType

Batch operation limits

Messages like Maximum 20 slides per bulk create or Maximum 50 elements per slide.

  • Limits: 20 slides per bulk create, 50 elements per slide, 50 element updates per bulk update, 20 text measurements per call
  • Fix: Split large operations into smaller batches within these limits

Mutually exclusive parameters

Messages like Provide either slideId or slideIds, not both or Exactly one of 'name' or 'deckId' must be provided.

  • Fix: Use one parameter or the other, not both. Check the tool description for which parameters are alternatives.

Slide number out of range

  • Slide numbers are 1-based (the first slide is 1, not 0). The number must be within the deck's current slide count.
  • Fix: Call slides_get_deck to check how many slides exist before referencing by number.

Image Errors

These errors occur when adding images via slides_add_image.

Source URL must use HTTPS

  • Image URLs must use https:// — http:// is not allowed.

Failed to fetch image / Request timed out

  • Cause: The image URL is unreachable, requires authentication, or takes too long to respond (10-second timeout).
  • Fix: Verify the URL is publicly accessible and returns a valid image. Try opening the URL in a browser to confirm.

SVG images are not supported / Content-Type must be image/*

  • Supported formats: PNG, JPEG, GIF, WebP
  • SVG is not supported for security reasons
  • The URL must return an image/* content type, not HTML or other formats

Image exceeds 10MB limit

  • Fix: Compress or resize the image before uploading. Maximum file size is 10 MB.

Grouping Errors

At least 2 elements are required to create a group

  • Groups must contain at least 2 elements. Provide an array with 2 or more element IDs.

Element is already in a group / All elements must be on the same slide

  • Elements can only belong to one group at a time. Ungroup first with slides_ungroup_elements before re-grouping.
  • All elements in a group must be on the same slide — you can't group elements across slides.

Preventing Errors

Most errors are avoidable by following the recommended workflow:

  1. Always start with slides_get_deck — confirms the deck exists, gives you all slide IDs and element IDs, and shows the canvas size
  2. Read before modifying — call slides_get_slides to inspect elements before updating or deleting them
  3. Use IDs from tool responses — don't guess or construct IDs manually; use the IDs returned by creation tools
  4. Check fonts and templates first — call slides_list_fonts and slides_list_templates before referencing font families or template IDs
  5. Validate image URLs — ensure HTTPS, publicly accessible, supported format (PNG, JPEG, GIF, WebP), and under 10 MB

Related

  • Agent Workflow — The 7-step workflow that prevents most errors
  • Connect via MCP — Setup and authentication for each platform
  • Add Images — Image requirements, supported formats, and sizing
  • Layouts — Available layout IDs and how to discover template layouts