Copy page

References

Troubleshooting

Common issues and solutions for Teachfloor app development.

CLI Issues

"Not logged in" Error

Symptoms:

Code
Error: Not logged in. Please run 'teachfloor login' first.

Solution:

Code
teachfloor login

Enter your credentials and select your organization.

---

"Login failed: Request failed with status code 400"

Cause: OAuth client not properly configured

Solution:

1. Check if API URL is correct:

Code
echo $API_URL

2. For self-hosted instances, ensure OAuth client is set up (see web-app/README.md)

3. Contact platform administrator to configure OAuth client

---

"Invalid token" Error

Cause: Token expired or corrupted

Solution:

Code
teachfloor logout
teachfloor login

---

"Not in app folder" Error

Symptoms:

Code
Error: This command must be run inside a Teachfloor extension app folder.

Solution:

Code
# Check for manifest file
ls teachfloor-app.json

# If not found, navigate to app folder
cd path/to/my-app

# Or create new app
teachfloor apps create my-app
cd my-app

---

CLI Command Not Found

Symptoms:

Code
bash: teachfloor: command not found

Solution:

Code
# Install globally
npm install -g @teachfloor/teachfloor-cli

# Verify installation
teachfloor version

# If still not found, check PATH
echo $PATH

# Use npx as alternative
npx @teachfloor/teachfloor-cli login

---

Build Issues

"npm run build" Fails

Symptoms:

Code
Module not found: Error: Can't resolve...

Solution:

Code
# Clear cache and reinstall
rm -rf node_modules
rm package-lock.json
npm install

# Clear webpack cache
rm -rf node_modules/.cache

# Try build again
npm run build

---

"Version already exists" Error

Symptoms:

Code
Error: Version 1.0.0 is already approved.

Solution: Increment version in teachfloor-app.json:

Code
{
  "version": "1.0.1"
}

Then upload again:

Code
teachfloor apps upload

---

Build Size Too Large

Symptoms: Warning about bundle size exceeding recommended limit

Solution:

Code
# Analyze bundle
npm install --save-dev webpack-bundle-analyzer
ANALYZE=true npm run build

# Reduce size:
# 1. Remove unused dependencies
npm uninstall unused-package

# 2. Use dynamic imports
const Component = lazy(() => import('./Component'))

# 3. Minify images
# 4. Tree-shake imports
import { Button } from '@teachfloor/extension-kit' // ✅
import * as Kit from '@teachfloor/extension-kit'    // ❌

---

Runtime Issues

App Not Displaying

Checklist:

1. Check viewport matches current page
2. Verify app is installed
3. Check browser console for errors
4. Verify SDK is loading

Solution:

Code
// Add debug logging
const { environment } = useExtensionContext()
console.log('Current viewport:', environment.viewport)
console.log('App initialized:', environment.initialized)

---

"Cannot read property of undefined"

Cause: Accessing context before initialization

Solution:

Code
// ❌ Bad
const { userContext } = useExtensionContext()
return <div>{userContext.name}</div> // Error!

// ✅ Good
const { userContext, environment } = useExtensionContext()

if (!environment.initialized) {
  return <Loader />
}

return <div>{userContext.name}</div>

---

Data Not Persisting

Cause: Missing permissions or incorrect source

Solution:

1. Check permissions in manifest:

Code
{
  "permissions": [
    {
      "permission": "user_read",
      "purpose": "Display your profile"
    }
  ]
}

2. Verify data source:

Code
// Correct source
await store('key', data, 'userdata')  // ✅
await store('key', data, 'appdata')   // ✅

// Wrong source
await store('key', data, 'wrong')     // ❌

3. Check for errors:

Code
try {
  await store('key', data, 'userdata')
  console.log('Saved successfully')
} catch (error) {
  console.error('Save failed:', error)
}

---

Permission Denied Errors

Symptoms:

Code
Error: Permission denied: user_read

Solution:

1. Add permission to manifest:

Code
teachfloor apps grant permission

2. Upload new version:

Code
teachfloor apps upload

3. Users may need to reinstall app to approve new permissions

---

Development Issues

Hot Reload Not Working

Solution:

Code
# Stop dev server (Ctrl+C)
# Clear cache
rm -rf node_modules/.cache

# Restart
teachfloor apps start

---

Port Already in Use

Symptoms:

Code
Error: Port 3000 is already in use

Solution: Change port in webpack.config.js:

Code
module.exports = {
  devServer: {
    port: 3001, // Change port
  }
}

Or kill process using port:

Code
# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

---

Changes Not Reflecting

Solution:

Code
# Hard refresh browser
Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

# Clear browser cache
# In DevTools: Right-click refresh → Empty Cache and Hard Reload

# Restart dev server
# Stop server (Ctrl+C)
teachfloor apps start

---

Manifest Issues

"Invalid manifest" Error

Cause: JSON syntax error or missing required fields

Solution:

Code
# Validate JSON syntax
cat teachfloor-app.json | jq .

# Check required fields
jq '.id, .version, .name' teachfloor-app.json

# Common issues:
# - Missing comma
# - Extra comma
# - Unquoted strings
# - Wrong bracket type

---

Component Not Found

Symptoms:

Code
Error: Cannot find module './MyView'

Solution:

1. Check component name matches manifest:

Code
{
  "ui_extension": {
    "views": [
      {
        "component": "MyView"  // Must match filename
      }
    ]
  }
}

2. Verify file exists:

Code
ls src/views/MyView.jsx

3. Check export:

Code
// Must use default export
export default MyView  // ✅
export { MyView }      // ❌

---

Browser Issues

Browser Console Errors

Common Errors:

1. "Uncaught ReferenceError: tf is not defined"

   • SDK not loaded
   • Check public/index.html has SDK script

2. "Cannot read property 'emit' of undefined"

   • Calling SDK before initialization
   • Wrap in useEffect with initialization check

3. "Failed to fetch"

   • CORS issue or network error
   • Check API URL
   • Verify network connection

---

App Shows Blank Page

Debug Steps:

1. Open browser console (F12)
2. Check for JavaScript errors
3. Verify platform is initialized:

Code
import { useExtensionContext } from '@teachfloor/extension-kit'

const { environment } = useExtensionContext()
console.log('Initialized:', environment.initialized)

4. Signal app is ready:

Code
import { initialize } from '@teachfloor/extension-kit'

initialize()

---

Installation Issues

Cannot Install npm Packages

Solution:

Code
# Clear npm cache
npm cache clean --force

# Delete lock file
rm package-lock.json

# Reinstall
npm install

# Try with legacy peer deps
npm install --legacy-peer-deps

---

Node Version Issues

Solution:

Code
# Check version
node --version

# Should be 18.0.0 or higher
# Install/switch version
nvm install 20
nvm use 20

---

Deployment Issues

Upload Fails

Symptoms:

Code
Error: Failed to upload app

Solution:

1. Check authentication:

Code
teachfloor whoami

2. Verify network:

Code
ping app.teachfloor.com

3. Check manifest is valid
4. Try again

---

Review Rejected

Common Reasons:

• Unclear permission purposes
• Security vulnerabilities
• Poor user experience
• Broken functionality
• Missing documentation

Solution:

1. Read rejection feedback carefully
2. Fix identified issues
3. Increment version
4. Upload and resubmit

---

Performance Issues

App Loading Slowly

Solution:

Code
// 1. Lazy load components
const HeavyComponent = lazy(() => import('./Heavy'))

// 2. Memoize expensive calculations
const result = useMemo(() => expensive(data), [data])

// 3. Debounce frequent operations
const debouncedFn = useMemo(
  () => debounce(fn, 500),
  []
)

// 4. Cache data
const cachedData = useMemo(() => data, [data])

---

High Memory Usage

Solution:

Code
// Clean up timers and intervals
useEffect(() => {
  const timer = setTimeout(() => {
    // Do something
  }, 1000)

  return () => {
    clearTimeout(timer)  // Cleanup!
  }
}, [])

// Clear timers
useEffect(() => {
  const timer = setTimeout(() => {}, 1000)

  return () => {
    clearTimeout(timer)  // Cleanup!
  }
}, [])

---

Getting Help

Before Asking for Help

1. Check browser console for errors
2. Check CLI output for error messages
3. Verify manifest is valid
4. Check this troubleshooting guide
5. Search GitHub issues

Where to Get Help

• GitHub Issues: teachfloor/teachfloor-cli/issues
• Email: support@teachfloor.com
• Community: community.teachfloor.com

What to Include

When reporting issues:

• Teachfloor CLI version (teachfloor version)
• Node version (node --version)
• Operating system
• Full error message
• Steps to reproduce
• Manifest file (if relevant)
• Console errors (screenshot)

---

Debug Mode

Enable Debug Logging

Add to public/index.html:

Code
<script>
  window._tfOpts = {
    id: 'your-app-id',
    debug: true  // Enable debug mode
  }
</script>

This will log SDK events to console.

---

Common Mistakes

1. Not Handling Loading States

Code
// ❌ Bad
const { userContext } = useExtensionContext()
return <div>{userContext.name}</div>

// ✅ Good
const { userContext, environment } = useExtensionContext()
if (!environment.initialized) return <Loader />
return <div>{userContext.name}</div>

2. Not Handling Async Operations

Code
// ❌ Bad
useEffect(async () => {
  const data = await retrieve('key')
  setData(data)
}, [])

// ✅ Good
useEffect(() => {
  retrieve('key').then(setData)
}, [])

3. Over-Requesting Permissions

Code
// ❌ Bad - requesting everything
"permissions": [
  { "permission": "user_read", ... },
  { "permission": "user_events_read", ... },
  { "permission": "course_read", ... },
  // ... not all needed
]

// ✅ Good - only what's needed
"permissions": [
  { "permission": "course_read", "purpose": "Display course info" }
]

4. Not Validating Data

Code
// ❌ Bad
await store('data', userInput, 'userdata')

// ✅ Good
if (!isValid(userInput)) {
  throw new Error('Invalid input')
}
const sanitized = sanitize(userInput)
await store('data', sanitized, 'userdata')

---

Quick Reference

Reset Everything

Code
# Logout
teachfloor logout

# Clear cache
rm -rf node_modules/.cache
rm -rf dist/

# Reinstall
rm -rf node_modules
npm install

# Login again
teachfloor login

# Rebuild
npm run build

Debug Checklist

Code
□ Check browser console for errors
□ Verify environment.initialized is true
□ Check manifest is valid JSON
□ Confirm permissions are listed
□ Verify component files exist
□ Check SDK script is loaded
□ Confirm app is installed
□ Check viewport matches page
□ Verify data storage permissions
□ Test with hard refresh

---

Additional Resources

• Quickstart Guide
• CLI Reference
• Best Practices
• Examples