6 Tips for Troubleshooting Common Ally Errors

Blackboard Ally is one of the most useful tools in your course accessibility toolkit. It scans your content, flags potential barriers, and offers step-by-step guidance for fixing them. However,  sometimes the guidance can be unclear, the fix doesn’t seem to work, or you’re not sure whether what Ally flagged is actually a problem. This article walks through the most common Ally errors faculty encounter, and what to do when the built-in guidance doesn’t get you all the way there.

1. Missing or Poor Alt Text on Images

Ally flags images that are missing alt text or have alt text that may not be meaningful (for example, a filename like “image001.jpg” used as alt text).

• Fix it in Blackboard: Click the Ally indicator next to the content item and follow the AI Alt Text Assistant prompts. You can accept an AI-generated suggestion or write your own. If it truly doesn’t contribute meaning or purpose to the content, you can mark it as decorative.

• Fix it in the source file: If the image is inside an uploaded Word, PowerPoint, or PDF, update the alt text in the original file and re-upload as a new version to replace the old file

When Ally’s guidance isn’t enough: Ally’s AI Alt Text Assistant is fairly sophisticated and provides an excellent starting point for complex images. However, if the image is a chart, diagram, or map, and your learning outcome requires more detail, a one-sentence description may not be sufficient. A long description, typically linked in a separate document, helps provide additional information or context.

2. Untagged or Poorly Tagged PDFs

Untagged PDFs are one of Ally’s most common and most frustrating flags. A PDF without accessibility tags cannot be read in order by a screen reader. Scanned PDFs are almost always untagged.

Image: Ally generates suggested tags for review and approval.

• Use Ally’s new auto-tagging feature: Ally will scan your PDF and generate tags based on the content in the PDF. You can review the suggested tags and approve the document to apply the tags. At this time, you cannot edit the tags or selectively approve the tags. 

• If you need to modify the tags and you have the original source file: Go back to Word, Google Docs, or PowerPoint, ensure the document is structured with headings and proper formatting, and re-export as a tagged PDF using “Save as PDF” (not print-to-PDF).

• If you need to modify the tags and you only have the PDF: Use Adobe Acrobat’s Accessibility Checker (Tools → Accessibility → Full Check) to identify and repair tagging issues. This takes more time, but is doable for shorter documents.

When Ally’s guidance isn’t enough: Consider whether the PDF can be replaced with content built directly in Blackboard, which is accessible by design. Blackboard can convert many files, including Microsoft Word and PowerPoint, to an accessible-friendly web format.

3. Document Language Not Set

Ally sometimes flags that a document’s language is not specified. This matters because screen readers use language metadata to apply the correct pronunciation rules.

• Using Ally: Ally will allow you to set the language per PDF from a simple dropdown menu at the time the issue is flagged. Ally will scan your document and suggest the language. Most languages are available.

When Ally’s guidance isn’t enough: If Ally does not have your document’s language, you can set the language in the source file within Word, Google Docs, and Adobe Acrobat.

4. Low Color Contrast

Ally flags content where text color does not have sufficient contrast against its background -- a barrier for students with low vision or color blindness. A contrast ratio of at least 4.5:1 for normal text is ideal.

• When Ally flags a file: Open the original document, update the text or background color, and re-upload.

• In Blackboard’s rich text editor, stick to the default text colors, which are already color contrast-compliant. 

• Avoid light gray text on white backgrounds, yellow text on white, or red text on green.

When Ally’s guidance isn’t enough: Use WebAIM’s free Contrast Checker to test any color combination before using it in course materials.

5. Missing or Skipped Heading Structure

Headings are essential navigation landmarks for screen reader users. Ally flags documents that lack headings or use heading levels out of order (for example, jumping from Heading 1 to Heading 3). 

• In Word and Google Docs: Apply heading styles from the Styles panel -- Heading 1 for your title, Heading 2 for major sections, Heading 3 for subsections. Don’t skip levels.

• In PowerPoint: Use the default slide title field for each slide’s title rather than inserting a text box.

• In Blackboard: Use the paragraph format dropdown in the rich text editor to apply heading levels to your content.

6. Missing Document Title

Ally may flag a document with a missing title, which is different from the document name. Instructors can set a title using Ally and quickly save this change. Titles may not have the following:

• use special characters or end in a period

• end with a file extensions (e.g., pdf, xls, doc)

• match the file name exactly

Ally’s built-in guidance covers most common scenarios, but some files require more hands-on support. If you’ve followed the guidance and the issue persists, or if you’re working with a complex document type you’re not sure how to fix, Instructional Technology is here to help. You can also reach us via RT to submit a ticket or schedule a 1:1 consultation.

• Attached Inline Image for 6 Tips for Troubleshooting Common Ally Errors